DEV Community

Cover image for Dokploy - Deploy a Postgres DB + Express API + Next.js app from GitHub
Nguezet Jordan Junior
Nguezet Jordan Junior

Posted on

Dokploy - Deploy a Postgres DB + Express API + Next.js app from GitHub

#automation #devops #docker #opensource

1. What is Dokploy

Dokploy is an open-source, self-hostable PaaS that uses Docker + Traefik to let you run apps and managed databases on your VPS with a web UI, Git integration, auto-deploy and TLS support. It’s designed to be an alternative to platforms like Heroku, Vercel or Netlify while keeping everything under your control. (dokploy.com)

2. How to install Dokploy

Quick install (recommended for most): run Dokploy’s installer on a fresh VPS (Ubuntu/Debian recommended). The docs show the one-line installer approach; you can also follow the manual install if you prefer to inspect scripts first. Example (as in Dokploy docs):

# example installer (copy from official docs before running)
curl -sSL https://dokploy.com/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

Security note: as always, audit remote install scripts before piping to sh — the docs include a manual install path if you want to download + inspect the script. (docs.dokploy.com)

Suggested VPS sizing: 1–2 vCPU, 2–4 GB RAM minimum for a small dev instance; increase for production. Many community tutorials add firewall and swap steps before installing. (MassiveGRID)

3. Launching Dokploy

After installation the Dokploy service runs as Docker containers on your server. You’ll access the panel at http(s)://<your-server-ip-or-domain>:PORT (by default the installer binds ports and configures Traefik). After initial login you’ll see the dashboard where you can create projects and services. (docs.dokploy.com)

Dokploy dashboard screenshot

4. Creating a project

In Dokploy a Project groups related services (e.g., my-app). From the dashboard: click Create Project → give it a name and optional description. Projects scope deployments, environment variables, and service access.

Create a project in dockploy

5. Types of services available in Dokploy

Dokploy supports multiple service types (examples):

  • Application (build from Git repo: Dockerfile / Node, etc.)
  • Docker Compose stacks (deploy entire docker-compose.yml) — great for multi-container apps.
  • Database services (managed Postgres, MySQL, Redis) that Dokploy can provision and back up.
  • Static sites / templates and third-party image-based services (Docker Hub images). (dokploy.com)

6. Creating a service in a project

You can add a service by either:

  • Pointing Dokploy to a GitHub repository (select branch + build options), or
  • Deploying a Docker Compose stack directly, or
  • Creating a managed database service via the UI.

Steps (GitHub example):

  1. In your project, click Create Service → choose Application.
  2. Select Git as source → choose GitHub (you’ll connect Dokploy to GitHub once per account). (docs.dokploy.com)
  3. Enter repo path, branch, and build command (if needed). Dokploy can auto-deploy on pushes (auto-deploy option). (docs.dokploy.com)

Placeholder for screenshot:
[Insert "Create Service" / GitHub connect screenshot]

Create Service

Service creation form

7. Service provider

When creating a service you typically choose:

  • Repository provider: GitHub (common), GitLab, or a direct Docker image.
  • Build method: Dockerfile (recommended for Node/Next), buildpack, or remote image.
  • Deployment mode: single container app vs compose stack.

Dokploy’s docs explain the GitHub connection flow — you’ll grant access with a token and can restrict repositories. (docs.dokploy.com)

8. Service configuration

Each service exposes a configuration panel with:

  • Build settings (Dockerfile path, build args)
  • Start command / entrypoint
  • Ports to expose (internal → routed via Traefik)
  • Resource limits (CPU, memory)
  • Environment variables (next section)
  • Volumes / persistent storage (for databases or file uploads)

Set the build context and port your app listens on (e.g., Express PORT=3000, Next PORT=3000 or use Next.js recommended next start settings for production builds).

Example: For a Next.js production app you build (npm run build) and then run npm run start on port 3000 configure Dokploy to expose that internal port.

9. Environment

Use Dokploy’s environment variables UI to provide secrets (DB credentials, JWT secrets, API keys). Best practices:

  • Store credentials (e.g., DATABASE_URL, JWT_SECRET) in the service’s env panel, not in the repo.
  • For multi-service stacks, define shared envs at the project level when possible (Dokploy supports scoping).
  • Use different env sets for production vs staging branches.

Example env for Express API (set in Dokploy):

Service configuration

PORT=4000
DATABASE_HOST=postgres-db     # service name (see internal comms)
DATABASE_PORT=5432
DATABASE_USER=app_user
DATABASE_PASSWORD=strong_password
DATABASE_NAME=app_db
JWT_SECRET=change_this_secret
Enter fullscreen mode Exit fullscreen mode

10. Internal communication to other services using service names and connection URLs (Postgres case)

When Dokploy runs multiple services in the same project, they share an internal Docker network. That means you can reference other services by the service name as the hostname.

Example architecture:

  • Service name: postgres-db (managed DB service or a container from docker-compose)
  • Express API uses host: postgres-db, port 5432

Connection string (Express / node-pg):

const { Pool } = require('pg');

const pool = new Pool({
  host: process.env.DATABASE_HOST || 'postgres-db',
  port: Number(process.env.DATABASE_PORT || 5432),
  user: process.env.DATABASE_USER,
  password: process.env.DATABASE_PASSWORD,
  database: process.env.DATABASE_NAME
});
Enter fullscreen mode Exit fullscreen mode

If Dokploy provisions a managed Postgres service, it will expose host/port/credentials in the service UI — copy those into your Express service envs. Internal DNS using service names only works when the DB is deployed inside the same Dokploy project/network (compose or container); hosted/managed DBs may have external hostnames which you should use instead. (dokploy.com)

Postgres service details screenshot showing host/port/credentials

11. Deployment

Two main flows:

A. Manual / UI deploy: push config in Dokploy and click Deploy on the service.

Manual / UI deploy

B. Auto-deploy via GitHub: connect GitHub and enable auto-deploy so every push to the chosen branch triggers a build and deployment (Dokploy supports webhooks + native GitHub integration). For CI you can also use the GitHub Action for Dokploy to trigger deployments as part of your workflow. (docs.dokploy.com)

Auto-deploy via GitHub

Typical deploy steps for our stack:

  1. Create a Project in Dokploy.
  2. Add Postgres service (managed or as compose).
  3. Add Express service (point to repo ./api with Dockerfile; set envs).
  4. Add Next.js service (point to repo ./frontend with Dockerfile; set envs).
  5. Ensure services expose correct ports and healthchecks.
  6. Click Deploy (or push to the branch if auto-deploy enabled).
  7. Inspect logs in Dokploy UI for build and runtime logs.

Troubleshooting tips:

  • If build fails, check build logs in the UI—missing build dependencies are common (node version mismatch, missing build args).
  • For DB connection errors check that the Express service envs match the database service credentials and that the DB is ready (use depends_on or retry logic).
  • Use health checks and readiness probes in your Dockerfile/start scripts.

12. Connecting the service to a domain name

Dokploy uses Traefik for routing and TLS management. Steps:

  1. In your DNS provider, create an A record for app.yourdomain.com pointing to your server IP.
  2. In Dokploy, open the service’s domain/route settings and set the hostname (app.yourdomain.com). Dokploy will map that hostname to the internal service and (usually) request a TLS certificate automatically via Let’s Encrypt (if configured). (dokploy.com)

If you run your own Traefik config (Dokploy allows editing Traefik file editor), you can customize certificate providers or add advanced routing rules.

Insert domain mapping / Traefik rules screenshot

13. Accessing the service online

After DNS propagation and successful deployment:

  • Visit https://app.yourdomain.com — Traefik will route to the Next.js service.
  • API endpoints will be under the path you configured (e.g., https://app.yourdomain.com/api/*) or on a subdomain like api.yourdomain.com if you prefer.
  • Use Dokploy logs and monitoring to verify runtime errors, request traces, and resource use.

If you used internal service names for backend-to-DB communication, those hostnames are only resolvable inside Dokploy’s network — external requests must go through the public domain / proxy.

Example: Minimal Dockerfiles

Express (./api/Dockerfile):

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 4000
CMD ["node", "dist/index.js"]
Enter fullscreen mode Exit fullscreen mode

Next.js (./frontend/Dockerfile) — production build + start:

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

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
EXPOSE 3000
CMD ["npm", "run", "start"]
Enter fullscreen mode Exit fullscreen mode

Final checklist before first production deploy

  • VPS firewall opened for HTTP/HTTPS, SSH locked down.
  • Dokploy installed and reachable. (docs.dokploy.com)
  • GitHub connected and auto-deploy configured if desired. (docs.dokploy.com)
  • Postgres credentials set securely in Dokploy env UI (or use managed DB service).
  • Health checks and resource limits applied.
  • DNS A records created, TLS validated by Dokploy/Traefik. (dokploy.com)

Troubleshooting common errors

  • Build fails: inspect build logs; confirm Node version and build scripts.
  • DB connection refused: confirm service name/port and that DB init finished; add retry/backoff in your app.
  • Domain shows default page or 404: check hostname mapping in Dokploy and verify DNS A record.
  • Auto-deploy not triggering: recheck GitHub webhook permissions and branch settings. (docs.dokploy.com)

Where to learn more / references

Top comments (0)