Deploy Marbes Backend using Docker Compose

Marbes Backend ships with multiple Docker Compose configurations that cover different deployment scenarios. The standard docker-compose.yml attaches the backend to pre-existing external networks shared with a frontend and database layer. The docker-compose.prod.yml spins up a self-contained production stack that includes PostgreSQL, Redis, Nginx, and an optional automated backup service. This page covers both paths and documents every environment variable the application reads.

Prerequisites

Docker Engine 24+ and Docker Compose V2
pnpm is used as the package manager inside the image — no local install needed
A .env file populated from env.example (see Environment variables below)

Deployment options

Standard deployment (external networks)

Use this when the backend joins an existing Docker network topology — for example, when a frontend, database, and backend are each managed by separate Compose files. The backend container expects three external networks to already exist before it starts:

Network	Purpose
`marbes_frontend_net`	Communication with the frontend service
`marbes_backend_net`	Internal backend traffic
`marbes_db_net`	Access to the PostgreSQL database

Create the networks once before your first deploy:

docker network create marbes_frontend_net
docker network create marbes_backend_net
docker network create marbes_db_net

Production deployment (self-contained stack)

docker-compose.prod.yml brings up all services in one command. It includes:

PostgreSQL 16 (Alpine) with a health check
Redis 7 (Alpine) with a health check
Backend API — starts only after both database services are healthy
Nginx reverse proxy on ports 80 and 443
Backup service (opt-in via the backup profile)

Deploy the backend

Copy and configure environment variables

Copy the example file and fill in your values:

cp env.example .env

At minimum, set the database credentials and a strong JWT secret before continuing. See Environment variables for the full list.

Never commit .env to version control. The file contains secrets that must stay out of your repository.

Choose your Compose file and start

Run one of the following commands depending on your scenario:

# Foreground — useful for verifying the first boot
pnpm docker:dev

# Detached (background)
pnpm docker:dev:detached

Verify the deployment

Once the container is running, hit the health endpoint to confirm the API is accepting requests:

curl http://localhost:7780/api/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 12.5,
  "environment": "production",
  "version": "1.0.0"
}

The Docker health check in both the Dockerfile and docker-compose.prod.yml calls this same endpoint every 30 seconds. A container that fails three consecutive checks will be marked unhealthy.

Tail the logs

# Backend logs only
pnpm docker:logs

# All services (prod stack)
pnpm docker:logs:all

Available Docker commands

All commands below are defined in package.json and run with pnpm <command>:

Command	Description
`docker:build`	Build the Docker image and tag it `marbes-backend`
`docker:run`	Run a standalone container on port `7780` using `.env`
`docker:backend`	Start the backend-only Compose file in the foreground
`docker:backend:detached`	Start the backend-only Compose file in the background
`docker:backend:down`	Stop and remove the backend-only Compose services
`docker:backend:logs`	Tail logs from the backend-only container
`docker:backend:restart`	Restart the backend service
`docker:backend:shell`	Open a shell inside the backend container
`docker:dev`	Start the default `docker-compose.yml` in the foreground
`docker:dev:detached`	Start the default `docker-compose.yml` in the background
`docker:prod`	Start the production stack in the foreground
`docker:prod:detached`	Start the production stack in the background
`docker:down`	Stop and remove the default Compose services
`docker:down:volumes`	Stop services and delete all named volumes
`docker:logs`	Tail backend service logs
`docker:logs:all`	Tail logs for all services
`docker:shell`	Open a shell inside the backend container
`docker:db`	Open a `psql` session inside the Postgres container
`docker:clean`	Prune unused images, containers, and volumes
`docker:reset`	Full teardown: stop, remove volumes, and prune Docker

Environment variables

Copy env.example to .env and set the following variables. Variables marked required will cause the application to fail to start or behave incorrectly if left at their default values in production.

General

Variable	Default	Required	Description
`NODE_ENV`	`development`	Yes	Set to `production` in production deployments
`PORT`	`7780`	No	Port the HTTP server listens on

PostgreSQL

Variable	Default	Required	Description
`DB_HOST`	`localhost`	Yes	Hostname or container name of the PostgreSQL server
`DB_PORT`	`5432`	No	PostgreSQL port
`DB_NAME`	`marbes_db`	Yes	Database name
`DB_USER`	`marbes_user`	Yes	Database user
`DB_PASSWORD`	`marbes_password`	Yes	Database password — change this before deploying
`DB_SSL`	`false`	No	Enable SSL for the database connection

Redis

Variable	Default	Required	Description
`REDIS_HOST`	`localhost`	No	Redis hostname or container name
`REDIS_PORT`	`6379`	No	Redis port
`REDIS_PASSWORD`	(empty)	No	Redis password if authentication is enabled

JWT

Variable	Default	Required	Description
`JWT_SECRET`	(placeholder)	Yes	Secret key used to sign and verify tokens
`JWT_EXPIRES_IN`	`24h`	No	Expiry duration for issued tokens (note: the auth service issues tokens with a 12 h hard-coded expiry)
`JWT_REFRESH_EXPIRES_IN`	`7d`	No	Expiry duration for refresh tokens

JWT_SECRET must be a long, random string in production. Any deployment using the placeholder value from env.example is critically insecure — tokens could be forged by anyone who knows the default value.

CORS and Socket.IO

Variable	Default	Required	Description
`CORS_ORIGIN`	`http://localhost:3000`	Yes	Allowed origin for CORS requests
`CORS_CREDENTIALS`	`true`	No	Whether credentials are included in CORS requests
`SOCKET_CORS_ORIGIN`	`http://localhost:3000`	Yes	Allowed origin for Socket.IO connections

File uploads

Variable	Default	Required	Description
`UPLOAD_PATH`	`./uploads`	No	Directory where uploaded files are stored
`MAX_FILE_SIZE`	`10485760`	No	Maximum upload size in bytes (default: 10 MB)

Credit application links

Variable	Default	Required	Description
`FRONTEND_URL`	`http://localhost:3000`	Yes	Base URL of the frontend — used to construct links sent to clients
`SOLICITUD_CREDITO_EXPIRA_HORAS`	`72`	No	How many hours a credit application link remains valid

Security

Variable	Default	Required	Description
`BCRYPT_ROUNDS`	`12`	No	Cost factor for password hashing
`RATE_LIMIT_WINDOW_MS`	`900000`	No	Rate-limiting window in milliseconds (default: 15 min)
`RATE_LIMIT_MAX_REQUESTS`	`100`	No	Maximum requests per window per IP

Logs

Variable	Default	Required	Description
`LOG_LEVEL`	`info`	No	Log verbosity level
`LOG_FILE_PATH`	`./logs/app.log`	No	Path to the log file

Network architecture

The standard docker-compose.yml connects the backend container to three external networks. These networks must be created independently and are shared across services managed by other Compose files.

[ Frontend container ] ── marbes_frontend_net ──┐
                                                  ▼
                                          [ Backend container ]
                                                  ▲
[ PostgreSQL container ] ── marbes_db_net ────────┘
          │
          └── marbes_backend_net (internal backend traffic)

The production Compose file (docker-compose.prod.yml) uses an isolated bridge network (marbes_network_prod, subnet 172.21.0.0/16) — all services communicate internally and only Nginx exposes ports 80 and 443 to the host.

Port mapping

Host port	Container port	Service
`7780`	`7780`	Backend API (standard deployment)
`80`	`80`	Nginx (production stack)
`443`	`443`	Nginx TLS (production stack)

Health check endpoint

GET /api/health is unauthenticated and used by Docker, load balancers, and monitoring tools to verify the API is up.

curl http://localhost:7780/api/health

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "uptime": 3600.42,
  "environment": "production",
  "version": "1.0.0"
}

Field	Type	Description
`status`	string	Always `"healthy"` when the process is running
`timestamp`	string	ISO 8601 timestamp of the response
`uptime`	number	Process uptime in seconds
`environment`	string	Value of `NODE_ENV`
`version`	string	Value of `npm_package_version` from `package.json`

Get Started

Core Concepts

Guides

Deploy Marbes Backend using Docker Compose

Prerequisites

Deployment options

Standard deployment (external networks)

Production deployment (self-contained stack)

Deploy the backend

Available Docker commands

Environment variables

General

PostgreSQL

Redis

JWT

CORS and Socket.IO

File uploads

Credit application links

Security

Logs

Network architecture

Port mapping

Health check endpoint

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​Prerequisites

​Deployment options

​Standard deployment (external networks)

​Production deployment (self-contained stack)

​Deploy the backend

​Available Docker commands

​Environment variables

​General

​PostgreSQL

​Redis

​JWT

​CORS and Socket.IO

​File uploads

​Credit application links

​Security

​Logs

​Network architecture

​Port mapping

​Health check endpoint

Build docs developers (and LLMs) love

Prerequisites

Deployment options

Standard deployment (external networks)

Production deployment (self-contained stack)

Deploy the backend

Available Docker commands

Environment variables

General

PostgreSQL

Redis

JWT

CORS and Socket.IO

File uploads

Credit application links

Security

Logs

Network architecture

Port mapping

Health check endpoint