Coder Local Docker Environment

This repository contains the Docker Compose configuration to run Coder locally with PostgreSQL.

Prerequisites

• Docker installed and running
• Docker Compose installed
• Minimum 2 CPU cores and 4 GB RAM

Architecture

This setup includes:

• Nginx: SSL/TLS termination proxy with automatic HTTP to HTTPS redirect
• Coder: Main application server (internal, accessed via nginx)
• PostgreSQL: Database backend

Setup

1. Generate SSL Certificates

Generate self-signed SSL certificates for local development:

./generate-ssl-certs.sh

This creates a self-signed certificate valid for 365 days. Your browser will show a security warning, which you can safely accept for development purposes.

2. Configure Environment Variables

Copy the example environment file and configure your credentials:

cp .env.example .env

Important: Edit .env and set a strong PostgreSQL password. The password should be complex and contain:

• At least 16 characters
• Mix of uppercase and lowercase letters
• Numbers
• Special characters

Example of generating a secure password:

openssl rand -base64 32

Update these variables in your .env file:

POSTGRES_USER=coder_admin
POSTGRES_PASSWORD=your_complex_password_here
POSTGRES_DB=coder

3. Start Coder

docker compose up -d

4. Access Coder

Open your browser and navigate to:

• HTTPS (recommended): https://localhost
• HTTP: http://localhost (automatically redirects to HTTPS)

Note: Since this uses a self-signed certificate, your browser will show a security warning. You can safely proceed by:

• Chrome/Edge: Click "Advanced" → "Proceed to localhost (unsafe)"
• Firefox: Click "Advanced" → "Accept the Risk and Continue"
• Safari: Click "Show Details" → "visit this website"

Follow the initial setup wizard to create your admin account.

Configuration

The .env file contains all configurable options:

Variable	Description	Default
CODER_ACCESS_URL	URL where Coder will be accessible	https://localhost
CODER_VERSION	Coder version to run	latest
CODER_REPO	Coder Docker image repository	ghcr.io/coder/coder
POSTGRES_USER	PostgreSQL username	coder_admin
POSTGRES_PASSWORD	PostgreSQL password	Must be set
POSTGRES_DB	PostgreSQL database name	coder

Security Note: Never commit your .env file to version control. It is included in .gitignore to prevent accidental exposure of credentials.

Managing Coder

View Logs

docker compose logs -f coder

Stop Coder

docker compose down

Restart Coder

docker compose restart

Reset Everything (Delete All Data)

docker compose down -v

Warning: This will remove all data including workspaces and the database.

SSL/HTTPS Configuration

Nginx SSL Proxy

The nginx service acts as an SSL termination proxy, providing:

• HTTPS encryption for all traffic
• Automatic HTTP to HTTPS redirection
• WebSocket support for Coder workspaces
• Modern TLS configuration (TLS 1.2/1.3)
• Security headers (HSTS, X-Frame-Options, etc.)

Self-Signed Certificates

The included generate-ssl-certs.sh script creates self-signed certificates for development. These certificates:

• Are valid for 365 days
• Include localhost and 127.0.0.1 as subject alternative names
• Will trigger browser security warnings (this is expected and safe for local development)

Production SSL Certificates

For production deployments, replace the self-signed certificates with proper certificates from a trusted Certificate Authority:

1. Obtain certificates from Let's Encrypt, your organization's CA, or a commercial provider
2. Place the certificate and key in nginx/ssl/:
   • Certificate: nginx/ssl/coder.crt
   • Private key: nginx/ssl/coder.key
3. Update CODER_ACCESS_URL in .env to match your domain
4. Restart the services: docker compose restart nginx

Persistent Data

The setup creates two persistent volumes:

• coder_data - PostgreSQL database storage
• coder_home - Coder configuration and data

Docker Socket Permissions (Linux)

If you encounter permission issues with the Docker socket on Linux, uncomment the group_add section in docker-compose.yaml and set your Docker group ID:

# Get your Docker group ID
getent group docker | cut -d: -f3

Update the group_add value in docker-compose.yaml with this ID.

Direct Database Access

The PostgreSQL database is accessible on port 5432 for debugging:

psql -h localhost -U coder_admin -d coder

You'll be prompted for the password you set in .env.

Troubleshooting

Coder won't start

• Check logs: docker compose logs coder
• Verify .env file exists and has correct values
• Ensure PostgreSQL is healthy: docker compose ps

Permission denied on Docker socket

• See "Docker Socket Permissions" section above
• Verify Docker daemon is running

Database connection issues

• Verify database credentials in .env match
• Check database health: docker compose ps database
• View database logs: docker compose logs database

Next Steps

After Coder is running:

1. Create your first template
2. Launch a workspace
3. Start coding!

For more information, visit the Coder documentation.