Best practice for zero-downtime deployments with database migrations?

[BittuChan]

Hey everyone 👋

I've been running Dokploy for a few months now and loving it, but I'm hitting a deployment pattern issue I can't quite solve cleanly.

The situation:

I have a Node.js app (Express + Postgres) deployed through Dokploy. When I push updates that include database migrations, I'm seeing brief downtime because:

1. New container starts
2. Migration runs (via npm run migrate in the start command)
3. During migration, old container is still serving traffic with outdated schema
4. If migration adds a required column, old container crashes on write operations

What I've tried:

• Running migrations in a separate deploy hook before the main deployment → couldn't find a clean way to do this in Dokploy
• Using healthchecks to delay traffic routing → but migration still runs while old container is live
• Manual migration runs via Dokploy terminal → works but defeats the automation

My current workaround:

I'm just accepting the 10-15 seconds of errors during migration window and relying on my frontend to retry failed requests. Not ideal for production though.

Questions:

1. Has anyone figured out a pattern for this? Maybe something with Dokploy's lifecycle hooks I'm missing?
2. Should I be using a different deployment strategy entirely (blue-green maybe)?
3. Is there a way to run a one-off container for migrations before the actual deployment?

I know this is more of a general deployment problem, but curious if Dokploy has any features that make this easier that I'm not aware of.

Running Dokploy 0.8.x if that matters.

Thanks in advance!

[Shiven0504]

hey @BittuChan , thanks for sharing your problem! I was recently able to figure this out after digging through the Dokploy docs and Docker Compose options.

The solution that worked for me:

Use Dokploy's Advanced Configuration to separate migration logic from app startup, combined with healthchecks to prevent traffic during migration.

Here's what I changed:

1. Update your Dockerfile

Instead of running migrations in the start command, use a separate entrypoint script:

# entrypoint.sh
#!/bin/sh
set -e

# Run migrations first
npm run migrate

# Then start the app
exec npm start

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .

# Make entrypoint executable
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

EXPOSE 3000
ENTRYPOINT ["/entrypoint.sh"]

2. Configure healthcheck in Dokploy

In your application settings → Advanced → Add this to Docker Labels or use the healthcheck option:

HEALTHCHECK CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))" || exit 1

Make sure your app has a /health endpoint that checks DB connectivity:

app.get('/health', async (req, res) => {
  try {
    await db.query('SELECT 1'); // Quick DB check
    res.status(200).send('OK');
  } catch (err) {
    res.status(500).send('DB not ready');
  }
});

3. Adjust deployment strategy

In Dokploy application settings:

• Set Deployment Strategy to "Rolling" (not "Recreate")
• This keeps old container running until new one is healthy

How it works:

1. New container starts
2. Entrypoint runs migrations
3. App starts up
4. Healthcheck keeps failing during migration
5. Once migration completes + app is ready, healthcheck passes
6. Dokploy routes traffic to new container
7. Old container gets terminated

Result: Zero user-facing downtime. Old container serves traffic while new one is getting ready.

4. For complex migrations (optional)

If your migrations are backward-incompatible, I also started using this pattern:

Deploy 1: Add new columns (nullable), deploy code that handles both schemas
Deploy 2: Backfill data, make code use new columns only
Deploy 3: Drop old columns

Yeah it's more work, but for production-critical stuff it's worth it.

[Shiven0504]

• If your migration takes >60 seconds, you might need to increase healthcheck timeout
• This assumes you're using Docker and not Nixpacks (didn't test with Nixpacks)
• For multiple replicas, make sure migrations are idempotent (use migration tools like knex, prisma, or node-pg-migrate that handle this)

---

Let me know if this helps or if you're running into any specific issues with this setup. Happy to share my full docker-compose.yml if needed.

[BittuChan]

Hii @Shiven0504, Tysm for your suggestions! The start_period was the key part I was missing initially. It sort of gives the container breathing room during migration without failing healthchecks prematurely.

Also discovered:

Dokploy's container logs now show the migration output clearly, which is nice for debugging failed migrations. You can see it in real-time under Monitoring → Logs while the deployment is happening.

For anyone else dealing with long-running migrations (30s+), might also want to look into:

• Running migrations as a separate job in CI/CD before Dokploy deployment (we're considering this for our staging env)
• Using a dedicated migration runner container that exits after completion (haven't tried this yet but saw it mentioned in another thread)

Anyway, issue solved on my end. Appreciate the nudge to actually read the healthcheck docs properly lol.

Marking this as resolved. Thanks :)