Deployment Configuration

Configure how your application is built and deployed. This covers everything from your Dockerfile to environment variables to health check endpoints.

Dockerfile

Reoclo expects a Dockerfile in your repository. This is used to build the Docker image directly on your target server.

Default Path

The default path is ./Dockerfile at the repository root. You can configure a different path in your application settings if your Dockerfile lives elsewhere (for example, ./docker/Dockerfile or ./services/api/Dockerfile).

Standard Docker Build

Reoclo runs a standard docker build command. Whatever works locally will work on Reoclo. There are no special requirements or custom build steps.

The build context is the repository root, so your Dockerfile can reference any files in the repo using relative paths.

Use Multi-Stage Builds

Multi-stage builds reduce image size by separating build dependencies from runtime dependencies. This speeds up deployments and reduces disk usage on your server.

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Runtime stage
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]

The final image only contains the runtime dependencies, not the build tools.

.dockerignore

Reoclo respects .dockerignore files. Use this to exclude files from the build context (for example, .git, node_modules, test files, documentation).

A smaller build context means faster uploads to the Docker daemon and faster builds.

Environment Variables

Environment variables are how you pass configuration and secrets to your application. Set them in the dashboard under Application → Settings → Environment Variables.

How They Work

1. You add environment variables in the dashboard (key-value pairs)
2. Reoclo encrypts them at rest
3. During deployment, Reoclo securely injects them into the container

Security Model

Environment variables are write-only after you save them. You can update or delete them, but you cannot read them back through the dashboard.

Store Secrets Elsewhere Too

Because environment variables are write-only in Reoclo, you cannot retrieve them later. Store them in your own password manager (1Password, Bitwarden, and so on) as well.

If you lose a secret and cannot read it back from Reoclo, you will need to regenerate it.

Common Use Cases

• Database connection strings
• API keys for third-party services
• Feature flags
• Application secrets (session secrets, signing keys)
• Service URLs

Example

DATABASE_URL=postgresql://user:[email protected]:5432/myapp
REDIS_URL=redis://cache.example.com:6379
API_KEY=sk_live_abc123xyz789
NODE_ENV=production

These are injected into your container as standard environment variables. Access them in your application code the same way you would locally.

Port Configuration

Specify the port your application listens on inside the container. This is set during application creation and can be updated in the settings.

Reoclo maps this to an available host port on the server. You do not choose the host port (it is allocated automatically), but you do specify the container port.

Example

If your application listens on port 3000 inside the container, set the port to 3000. Reoclo might map this to a host port on the server, but your application code does not need to know that. It just listens on 3000 as usual.

Health Check

Define a health check path that Reoclo polls after starting a new container. This is critical for safe deployments.

What Makes a Good Health Check

A good health check verifies your application is ready to serve requests, not just that the process started.

Bad health check:

app.get('/health', (req, res) => {
  res.status(200).send('OK');
});

This returns 200 as soon as the HTTP server starts, even if the database connection is broken or the cache is not ready.

Good health check:

app.get('/health', async (req, res) => {
  try {
    // Verify database connectivity
    await db.ping();

    // Verify cache connectivity
    await cache.ping();

    // Check critical dependencies
    if (!config.isValid()) {
      throw new Error('Invalid configuration');
    }

    res.status(200).json({ status: 'healthy' });
  } catch (error) {
    res.status(503).json({ status: 'unhealthy', error: error.message });
  }
});

This checks that all critical dependencies are available before returning 200.

Verify Actual Readiness

Use a health check that verifies your app is actually ready to serve requests, not just that the process started. Check database connectivity, cache warmth, configuration validity, and any other critical dependencies.

If your app takes 30 seconds to warm up, your health check should fail during those 30 seconds and only pass when the app is truly ready.

Health Check Timeout

If your health check does not respond with HTTP 200 within the timeout period, the deployment fails and rolls back to the old container.

Make sure your health check responds quickly (under 5 seconds is ideal). If your app needs a long warmup, consider implementing a readiness check that returns 503 during warmup and 200 when ready.

Common Paths

• /health
• /api/health
• /healthz
• /_health

Choose a path that does not conflict with your application routes.

Docker Compose Services

The health check settings on this page apply to Dockerfile and image deployments. For a Docker Compose application, Reoclo reads service state from docker compose ps after docker compose up. It checks the selected compose service, or every service in the file when no service is selected:

• Each checked service must be running. When no service is selected, a service that exited with code 0 (a one-shot job such as a migration) counts as complete, but the service named like the application must be running, and at least one service must be running.
• If the compose file defines a healthcheck: for a checked service, that service must also report healthy. Reoclo waits while Docker reports starting, up to about two minutes.

If a service is not running or not healthy, the deploy log shows the state of each service and the last log lines of the service, and the deploy is rolled back. If Reoclo cannot read the service state at all (for example docker compose ps fails), it leaves the containers in place and reports that, so you can inspect the server.

The service does not need to publish a host port. A service that only uses expose: (for example, one that sits behind a reverse proxy on the Docker network) verifies the same way. Use a compose healthcheck: to make the deploy wait for real readiness:

services:
  api:
    build: .
    expose:
      - "3000"
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 20s

On a server that runs the managed proxy, a compose service does not publish the ports: from its compose file when you select a compose service for the application, the application has a bound domain, and its proxy enforcement is set to Enforce. Reoclo resets that list at deploy time, so the proxy is the only way in and it never has to recreate the container to remove a host port. Set the application’s enforcement to Opt out to keep the host ports. This needs Compose 2.24 or newer on the server. With an older Compose the deploy log says so, and the proxy removes the host ports after the deploy instead. An application that deploys a whole compose file without a selected service keeps its host ports at deploy time, and the proxy removes them afterwards.

Environment, Resource Limits and Builds for Docker Compose

When you select a compose service for the application, Reoclo passes the application’s environment variables and linked secrets to that service through a small compose file it generates at deploy time. Your compose file does not need env_file: .env, and it is never rewritten. Values under the service’s own environment: still win, and any env_file entries you declare are kept. Other services in the file only see the Reoclo environment through ${VAR} interpolation, so add env_file: .env to any of them that need it. Without a selected service, the environment is written to .env for interpolation only, and the deploy log says so.

The application’s resource limits apply to the selected service when they differ from the defaults (1 CPU, 512 MB) and your compose file does not set that limit itself. A limit in the compose file (mem_limit, cpus or deploy.resources.limits) always wins. The deploy log lists the limits Reoclo applied.

A deploy builds the selected service together with every service it depends on through depends_on, so a dependency with a build: section is rebuilt and recreated when its source changes. This needs Compose 2.24 or newer. With an older Compose, only the selected service is built, and the deploy log says so.

On a server that runs the managed proxy, a routed compose service joins the proxy network when its container is created, so its domain keeps serving through a redeploy.

Auto-Deploy

Enable auto-deploy to trigger deployments automatically when you push to the configured branch. This uses the GitHub App webhook to detect pushes.

See Wait for CI before a deployment to make an automatic deployment wait for the commit’s CI checks first.

When to Enable

• Staging environments: Auto-deploy keeps your staging server in sync with the latest code
• Development servers: Continuous deployment for rapid iteration
• Preview environments: Automatically deploy feature branches

When to Disable

• Production apps: Manual approval before deploying to production
• Regulated environments: Compliance requirements for change control
• High-traffic apps: Controlled deployment windows to minimize risk

You can enable or disable auto-deploy at any time in the application settings.

Build Context

The entire repository is cloned to the server (shallow clone for speed). The Docker build context is the repository root.

This means your Dockerfile can reference any files in the repo:

COPY package.json ./
COPY src/ ./src/
COPY public/ ./public/

All of these paths are relative to the repository root.

Build Arguments

If you need to pass build arguments to docker build, you can configure them in the application settings. These are passed as --build-arg flags.

Example use case: passing a build timestamp or commit SHA into the image.

ARG BUILD_TIME
ARG COMMIT_SHA

LABEL build_time=$BUILD_TIME
LABEL commit_sha=$COMMIT_SHA

Deployment Logs

Every deployment generates a full log of the pipeline execution. You can view these logs in the dashboard by clicking on a deployment in the history.

Logs include:

• Repository clone output
• Docker build output (all layers)
• Container startup output
• Health check results
• Rollback output (if the deployment failed)

Use these logs to debug build failures, health check failures, or runtime errors.

Configuration as code (reoclo.yml)

Everything on this page also has a file form: reoclo.yml. Reoclo reads the file from your repository at each deployed commit.

The file lives in one of two locations:

• <base_directory>/reoclo.yml: the file’s location identifies the application.
• ci/reoclo/<label>.yml: one file for each application, with a top-level app: selector.

When the file sets a key, the file’s value wins over the dashboard setting for that key. When the file does not set a key, the dashboard setting applies. The dashboard shows Set by reoclo.yml on a setting the file controls.

The setup wizard’s repository scan finds these files at the same two locations. See the reoclo.yml reference for every key, its type, and its default.

Next Steps

• Understand the deployment pipeline to see how all these pieces fit together
• Review security practices to understand how environment variables are protected
• Set up server connections to configure where your code deploys