Coolify

Deploy applications with Envshed secrets on Coolify, the open-source PaaS. This guide covers configuring Coolify to pass Envshed service tokens into Docker builds so secrets are injected at both build time and runtime.

Prerequisites

• A running Coolify instance with a project and service configured
• An Envshed account with a project and environment set up
• A service token with read access to the target environment
• A Dockerfile that uses envshed run (see Docker Integration)

Overview

Coolify builds your Docker image and manages container lifecycle. Envshed handles secret injection. The flow is:

1. Coolify triggers a build from your Git repository
2. The Dockerfile installs envshed and uses envshed run to inject secrets during build
3. At runtime, the container starts with envshed run wrapping your start command
4. Coolify passes ENVSHED_TOKEN and ENVSHED_ENVIRONMENT via environment variables

Step 1: Create a Service Token

Generate a service token scoped to the environment you're deploying:

envshed token create-service \
  -o my-org \
  -n "Coolify Production" \
  -s environment \
  --project-id <project-uuid> \
  --environment-id <environment-uuid> \
  -p read

Or from the dashboard: navigate to your organization, click Service Tokens, and create a new token.

Copy the token — it starts with envshed_svc_ and won't be shown again.

Step 2: Prepare Your Dockerfile

Use the multi-stage pattern from the Docker Integration guide. The key parts:

# Build stage: inject secrets during build
ARG ENVSHED_ENVIRONMENT
ARG ENVSHED_TOKEN

RUN if [ -n "$ENVSHED_TOKEN" ]; then \
      pnpm add -g envshed && \
      envshed run -e $ENVSHED_ENVIRONMENT -- pnpm build; \
    else \
      pnpm build; \
    fi

# Runner stage: inject secrets at container start
RUN pnpm add -g envshed

CMD ["sh", "-c", "envshed run -e $ENVSHED_ENVIRONMENT -- node server.js"]

Make sure .envshed.json is copied into the image or pass org/project/env explicitly via flags.

Step 3: Configure Coolify

General Settings

In your Coolify service configuration:

Setting	Value
Build Pack	Dockerfile
Base Directory	/ (or your monorepo root)
Dockerfile Location	Path to your Dockerfile (e.g., /apps/my-app/Dockerfile)

For monorepos, set Watch Paths to only trigger builds when relevant files change:

apps/my-app/**
packages/**

Custom Docker Options

In the Build section, add the build argument to pass the service token at build time:

--build-arg ENVSHED_VERSION=${envshed env-version}

info

The ENVSHED_TOKEN and ENVSHED_ENVIRONMENT build args are automatically forwarded from Coolify's environment variables to the Docker build when using Dockerfile build pack. Coolify passes all environment variables as build args by default when Use Docker Build Secrets is unchecked.

Environment Variables

Navigate to the Environment Variables tab and add:

Variable	Value	Description
ENVSHED_ENVIRONMENT	production	The Envshed environment to pull secrets from
ENVSHED_TOKEN	envshed_svc_...	Your service token

Add the same variables to Preview Deployments Environment Variables if you use Coolify's preview deployment feature (typically with a staging or preview environment).

Network Settings

Configure ports as needed for your application:

Setting	Value
Ports Exposed	80 or 3000 (your app's port)
Ports Mappings	e.g., 3000:3000

Step 4: Deploy

Click Redeploy in Coolify. The build log should show envshed fetching secrets:

$ envshed run -e production -- pnpm build
✓ 12 secrets loaded

And on container start:

$ envshed run -e production -- node server.js
✓ 12 secrets loaded

Full Example: Next.js on Coolify

Here's a complete setup for deploying a Next.js app:

Dockerfile

FROM node:22-slim AS dependencies
RUN corepack enable pnpm
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

FROM node:22-slim AS builder
RUN corepack enable pnpm
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
ARG ENVSHED_ENVIRONMENT
ARG ENVSHED_TOKEN
RUN if [ -n "$ENVSHED_TOKEN" ]; then \
      pnpm add -g envshed && \
      envshed run -e $ENVSHED_ENVIRONMENT -- pnpm build; \
    else \
      pnpm build; \
    fi

FROM node:22-slim AS runner
RUN corepack enable pnpm
WORKDIR /app
ENV NODE_ENV=production
ENV HOSTNAME="0.0.0.0"
RUN pnpm add -g envshed
COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static
COPY --from=builder --chown=node:node /app/.envshed.json ./.envshed.json
USER node
EXPOSE 3000
CMD ["sh", "-c", "envshed run -e $ENVSHED_ENVIRONMENT -- node server.js"]

next.config.js

Make sure standalone output is enabled:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
};

module.exports = nextConfig;

Coolify Settings

Setting	Value
Build Pack	Dockerfile
Base Directory	/
Dockerfile Location	/Dockerfile
Ports Exposed	3000

Coolify Environment Variables

ENVSHED_ENVIRONMENT=production
ENVSHED_TOKEN=envshed_svc_...

Multiple Environments

To deploy staging and production from the same repo, create two Coolify services pointing to the same repository but with different environment variables:

Service	ENVSHED_ENVIRONMENT	ENVSHED_TOKEN
my-app-staging	staging	Token scoped to staging
my-app-production	production	Token scoped to production

Use separate service tokens for each environment with the narrowest possible scope.

Troubleshooting

Build fails with "envshed: command not found"

The CLI isn't installed in the build stage. Make sure pnpm add -g envshed runs before the envshed run command in your Dockerfile.

Secrets not available at build time

Verify that Coolify is forwarding environment variables as build arguments. Check the Environment Variables tab and confirm ENVSHED_TOKEN and ENVSHED_ENVIRONMENT are set. You can also explicitly add --build-arg ENVSHED_TOKEN in Custom Docker Options.

Container starts but app crashes with missing env vars

1. Check that ENVSHED_TOKEN and ENVSHED_ENVIRONMENT are set in Coolify's environment variables (not just as build args)
2. Verify the .envshed.json file is copied into the final Docker stage
3. Check the Coolify logs for envshed error messages

"Failed to fetch secrets (HTTP 401)"

The service token is invalid or expired. Generate a new token and update Coolify's environment variables.

Preview deployments use wrong environment

Make sure the Preview Deployments Environment Variables section has the correct ENVSHED_ENVIRONMENT value (e.g., staging instead of production).