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 (e.g., ./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 (e.g., .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, they’re securely injected 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 can’t retrieve them later. Store them in your own password manager (1Password, Bitwarden, etc.) as well.

If you lose a secret and can’t read it back from Reoclo, you’ll 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 don’t choose the host port (it’s 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 doesn’t 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 isn’t 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 doesn’t 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 doesn’t conflict with your application routes.

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.

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.

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