How To Deploy A Full-Stack App With PostgreSQL To A VPS

Deploying a full-stack application to your own VPS usually means configuring several moving parts: building the app, running PostgreSQL, connecting both containers, setting up a reverse proxy, and enabling HTTPS.

This guide shows how to deploy the application and database with QuickDeploy. The final setup keeps the app and PostgreSQL on the same private Docker network, persists the database on the server, and exposes only the web application through your domain.

What You Will Deploy

The deployment contains:

• Your full-stack application in a Docker container.
• PostgreSQL in a separate Docker container.
• A private Docker network connecting the application and database.
• A persistent directory for PostgreSQL data.
• Caddy as the HTTPS reverse proxy for your domain.

QuickDeploy creates and manages these resources on your VPS. You still own the server, Docker configuration, application, and data.

Prerequisites

Before starting, make sure you have:

• An Ubuntu-based VPS with Docker and Docker Compose installed.
• A domain or subdomain with an A record pointing to the VPS.
• QuickDeploy installed and configured.
• A full-stack application that can read its database connection from an environment variable.
• A production start command for the application.

If your server is not ready yet, follow the Linux VPS setup guide.

Choose A Project Name

QuickDeploy uses the project name to keep related containers and data together. This guide uses myapp.

The PostgreSQL container will therefore be reachable inside Docker as:

myapp-postgres

Use the same project name for future deployments so QuickDeploy updates the existing application instead of creating another project.

Configure The Database Connection

Create a .env.production file in your application root. QuickDeploy includes this file when building the app and makes it available to the running container.

DATABASE_URL=postgresql://quickdeploy_app:YOUR_RANDOM_PASSWORD@myapp-postgres:5432/quickdeploy_app

Replace YOUR_RANDOM_PASSWORD with a long, unique password. Use the exact same value in the deployment command below.

The database hostname is myapp-postgres, not localhost. The app and database run in separate containers, so localhost inside the application container refers only to the application container itself.

Do not commit .env.production to Git. Add it to .gitignore if it is not already ignored:

.env.production

Check The Application Port

QuickDeploy needs to know which port the application listens on inside its container. For example, a typical Next.js application listens on port 3000.

Make sure the application listens on 0.0.0.0, not only 127.0.0.1. A custom Nixpacks start command can be configured in nixpacks.toml when framework detection does not choose the correct command:

[phases.build]
cmd = "npm run build"

[start]
cmd = "npm run start"

See the runtime configuration documentation for more information.

Deploy The App And PostgreSQL

From the application directory, run:

quickdeploy push \
  --domain app.example.com \
  --project myapp \
  --port 3000 \
  --db postgres \
  --db-port 5432 \
  --db-user quickdeploy_app \
  --db-password 'YOUR_RANDOM_PASSWORD' \
  --db-name quickdeploy_app

Change:

• app.example.com to your domain.
• 3000 to the port used by your application.
• YOUR_RANDOM_PASSWORD to the password from .env.production.

QuickDeploy uploads the project, builds the application image on the VPS, creates PostgreSQL when it does not already exist, starts the containers, configures Caddy, and points the domain to the healthy application container.

Verify The Deployment

Open your domain after the command finishes:

https://app.example.com

HTTPS certificate provisioning can take a short moment during the first deployment.

If the application starts but cannot reach PostgreSQL, check these common causes:

1. The project name in the command must match the hostname in DATABASE_URL.
2. The database user, password, and database name must match in both places.
3. The application must use myapp-postgres, not localhost, as its database host.
4. The application must listen on the port passed through --port.

You can inspect the project containers on the server with:

docker compose -f ~/myapp/docker-compose.yml ps

Run Database Migrations

Applications using Prisma, Django, Rails, Laravel, or another migration system need to apply their production migrations.

The safest approach depends on the framework. You can include the migration in your production start process when it is safe to run repeatedly, or execute it in the active application container after deployment.

Always back up production data before running a destructive migration.

Deploy Updates

Use the same command when shipping a new version. QuickDeploy builds the new application container, checks that it stays running, switches Caddy to it, and then removes the previous application container.

The PostgreSQL service and its data directory remain part of the project instead of being recreated for every application update.

Back Up PostgreSQL

QuickDeploy stores the PostgreSQL data below the project directory on your VPS:

~/myapp/data/postgres

Application deployment does not replace this directory. You should still create regular off-server backups. Also back up the database before removing the project, because removing a deployment can delete its project files and database data.

Deploy Without Giving Up Your Server

This setup gives you a conventional Docker and PostgreSQL deployment without requiring a hosted application platform. You can inspect the generated Compose file, connect other services, move the project, or manage the containers yourself.

QuickDeploy packages the repetitive deployment steps into one command while keeping the application and data on infrastructure you control.

Get QuickDeploy and deploy your first full-stack application.