Skip to main content

Install

Install

For a quick try on your laptop without domains or TLS, start with the Local quickstart (cmpatch selfhost local-eval). That page also covers reaching a real phone through ngrok before you have a domain.

To deploy Patch for production, you can either use a server and domain you own, or install on Fly.io. There is an install wizard for both paths, and each requires minimal input.

For either route, you will need a GitHub, Bitbucket Cloud, or GitLab account for sign-in (the installer walks you through creating its OAuth app).

Installing on a server​

To deploy with your own domains you will need:

  • A server you can reach over SSH
  • Access to a DNS host, with a domain you can add subdomains to for Patch
  • A CDN in front of storage (Cloudflare or CloudFront). Optional, but recommended for production

Machine size​

The default Compose install runs Caddy, the API and release worker, Postgres, and Silo on one host.

  • RAM: 2 GB is enough for typical use.
  • CPU: 1 vCPU is enough for typical use.
  • Disk: tens of GB is fine to start. Postgres uses approximately 2GB per 100k users.
  • Ports: Ports 80 and 443 need to be open.

The installer can also set up storage on Cloudflare R2, Amazon S3, or Google Cloud Storage instead if you want them to be separate. The installer can create the two necessary buckets or walk you through the console.

Run the installer​

Install the CLI on your own machine (Node.js >=20) and start the installer by running:

npm install -g @codemagic/patch-cli

cmpatch selfhost install

The command connects over SSH. A few steps ask for a value. The rest run on their own. An unattended run is possible too. The flags are in Scripted install.

When running the wizard, it will:

  1. Check the server, and install Docker, git, or curl if they are missing.
  2. Ask for the server address, and where release files should live.
  3. Ask for DNS. On Cloudflare it can add the records for you.
  4. Walk you through creating the OAuth app, then ask for the administrator email.
  5. Ask whether downloads should go through a CDN. You can skip this.
  6. Build the images, start the stack, and get the HTTPS certificates. The first build takes about 5-10 minutes.
  7. Finish the CDN once the server is up.

On a free Cloudflare plan, a name two levels under the domain (storage.updates.example.com) needs an extra certificate. CDN settings has the detail.

You can also start from the app: cmpatch init in a React Native project offers to install a server, signs you in, and links the project in one run.

When it finishes you'll have:

Dashboard:      https://updates.example.com/
API URL:        https://updates.example.com           (app config: CodemagicPatchApiUrl)
Download base:  https://storage-updates.example.com/codemagic-patch   (app config: CodemagicPatchDownloadBaseUrl)

Sign in to the dashboard with your chosen provider to create the administrator account, then connect your machine with cmpatch login and create apps and deployments (or use the dashboard). See Web dashboard.

warning

.env.selfhost on the server holds production secrets. Back it up and never commit or expose it.

Installing on Fly.io​

cmpatch selfhost install --fly deploys Patch onto Fly.io from this machine. You do not need your own domain or server.

cmpatch selfhost install --fly

The command runs on this machine. A few steps ask for a value. The rest run on their own.

When running the wizard, it will:

  1. Install flyctl and the Tigris CLI if they are missing, sign you in to Fly, and send you to add billing details.
  2. Ask for the company name, the region, and where you want Postgres.
  3. Create a public bucket and a private bucket, then sign you in to Tigris. Choose Sign in with Fly.io.
  4. Walk you through creating the OAuth app, then ask for the administrator email.
  5. Create a Postgres machine on Fly if you chose a new database. The first build takes several minutes.
  6. Build the Patch app on Fly and wait until the server answers. The machines suspend when idle.

When it finishes you'll have:

Dashboard:      https://<company>-patch.fly.dev/
API URL:        https://<company>-patch.fly.dev           (app config: CodemagicPatchApiUrl)
Download base:  https://<company>-patch.t3.tigrisfiles.io   (app config: CodemagicPatchDownloadBaseUrl)

<company> is the company name you enter, lowercased with hyphens. A Fly install has no custom domain and no CDN. Tigris keeps copies of the bundles close to the devices that fetch them, so you can go without a separate CDN for much longer than when running Patch on a server. Both addresses are built into the app binary, so changing either one later means a new store build.

Sign in to the dashboard with your chosen provider to create the administrator account, then connect your machine with cmpatch login and create apps and deployments (or use the dashboard). See Web dashboard.

Backups, restores, and upgrades on Fly: Ongoing maintenance.