Deploy from GitHub

You point Symplax at a GitHub repository and a server. Symplax builds a Docker image from your code on its own build machines, ships the image to your server, health checks it, and only then sends traffic to it. Your server never compiles anything.

​

Deploy your first app

You need a connected server first. See Connect a server or Buy a server. The first deploy usually takes a few minutes. Later deploys reuse the build cache and are faster.

​

How Symplax builds your code

If your root directory contains a Dockerfile, Symplax builds it as is. That is the way to deploy any language or setup the detector does not cover. Without a Dockerfile, Symplax looks at the files in your root directory and writes one for you. It checks for these, in this order: If nothing matches, the build stops and asks you to add a Dockerfile. For Node.js, Symplax uses the Node version you ask for in engines.node, .nvmrc or .node-version, and Node 20 if you name none. It installs with npm, Yarn or pnpm depending on which lockfile you commit.

​

Port and health check

Symplax picks the port your app listens on in this order:

1. A PORT environment variable, if you set one.
2. The EXPOSE line in the Dockerfile, yours or the generated one.
3. The Port in your app’s Settings.
4. 3000.

Your app must listen on 0.0.0.0, not localhost, or Symplax cannot reach it from outside the container. Before your new version gets traffic, Symplax probes it on that port. By default it tries /health first. If that answers with a 2xx or 3xx, it keeps using /health. Otherwise it accepts any HTTP response on /. The new version must pass three checks in a row within 60 seconds. To use a specific endpoint, set Health Check in Settings to a path and the status code it returns, for example /api/health and 200.

​

Your free subdomain

Every app gets an address like my-app.symplax.app, made from the app name, with HTTPS already working. If the name is taken, Symplax adds a short suffix. The subdomain stays with the app even after you add your own domain. See Domains and SSL.

​

Auto-deploy on push

When you create an app from GitHub, Symplax registers a webhook on the repository. Every push to the app’s branch starts a new deploy. For an app with a root directory, only pushes that change files inside it count. See Monorepos. You can turn this off with the Auto Deploy toggle in the app’s CI/CD tab. The CI/CD tab also has:

• Branch: change which branch the app follows.
• Concurrent builds: what happens when a push arrives during a build. queue waits, cancel stops the running build, skip ignores the new push.
• Build Filters: deploy only when certain paths change, or never when only certain paths change. See Monorepos.
• Deploy Hook: a URL you can POST to from any CI tool to start a deploy.
• Notifications: Slack and Discord webhooks.

To deploy only after your tests pass, turn off auto-deploy and run npx symplax deploy <app> as the last step of your CI. See the CLI guide.

​

Zero-downtime swap

Your old version keeps serving while the new one starts. Symplax runs the new image as a separate container, waits for it to pass the health check, then swaps the two and points nginx at the new one. It checks the new container again after the swap. If that check fails, Symplax puts the previous container back. The old container is removed only after the new one has proven stable. If the new version never passes, nothing changes for your visitors: the previous version stays live.

​

Build logs

The deploy view streams every line as it happens, through each phase: preparing, building, delivering the image to your server, starting it, verifying and routing. Errors are highlighted in red. Past deploys are listed in the History tab, and your running app’s output is in Logs.

​

When a build fails

Symplax reads the failed build or startup log and, for problems it recognises, shows what went wrong and how to fix it above the logs. It recognises, among others:

• package-lock.json or yarn.lock out of sync with package.json
• An app that needs a newer Node version than it was given
• A missing build script, or a build tool that was never installed
• A build that ran out of memory
• A native module that needs a compiler
• A COPY in the Dockerfile that points outside the root directory
• A build that tries to reach a database on localhost, or a database it cannot resolve
• Next.js failing to prerender a page
• A container that crashed on startup, never listened on its port, or returned server errors

On the Pro and Team plans you can also click Ask Buddy for an AI explanation of the failure, based on the logs.

​

Related