Deploy code-server with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it perfect for running a cloud IDE accessible from any device.

This guide walks you through deploying code-server (VS Code in the browser) with password authentication, persistent workspace storage, and automatic HTTPS using the LinuxServer.io image.

Prerequisites

• A VPS with at least 2 vCPUs, 2 GB RAM, and 20 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., code.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  code-server:
    image: lscr.io/linuxserver/code-server:latest
    restart: unless-stopped
    ports:
      - "8443:8443"
    environment:
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      - TZ=${TZ:-UTC}
      - PASSWORD=${PASSWORD}
      - SUDO_PASSWORD=${SUDO_PASSWORD:-}
      - DEFAULT_WORKSPACE=${DEFAULT_WORKSPACE:-/config/workspace}
    volumes:
      - ../files/code-server-config:/config
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8443/healthz || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3

Note: This guide uses the LinuxServer.io image which provides better environment variable support and runs on port 8443. The official codercom/code-server image is also available but uses different volume paths and configuration.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
PASSWORD	Web GUI login password	a-strong-password
SUDO_PASSWORD	Sudo password for terminal access (optional)	another-strong-password
PUID	Process user ID	1000
PGID	Process group ID	1000
TZ	Server timezone	America/New_York
DEFAULT_WORKSPACE	Directory opened on startup	/config/workspace

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. For stronger security, use HASHED_PASSWORD instead of PASSWORD — generate it with echo -n "your-password" | npx argon2-cli -e.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/code-server-config — VS Code settings, extensions, SSH keys, workspace files, and all project data

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths (e.g., /opt/code-server) because Dokploy may clean them during redeployment.

Your workspace files live in /config/workspace inside the container. Store all your projects here to ensure they persist across redeployments. SSH keys for Git can be placed in /config/.ssh.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., code.yourdomain.com)
3. Set the container port to 8443
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your code-server container. HTTPS is important for code-server to protect your password and code in transit.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — you should see the code-server container pull and start
3. Check the Logs tab for the code-server service. Look for startup messages indicating the server is ready
4. Open https://code.yourdomain.com in your browser — you should see the code-server password prompt
5. Enter your PASSWORD to access the VS Code interface
6. Open the integrated terminal and verify you can run commands. Install your preferred development tools as needed

Troubleshooting

"Invalid password" even with correct password Verify the PASSWORD environment variable is set correctly in Dokploy. If using HASHED_PASSWORD, ensure the hash was generated correctly with argon2. Redeploy after changing the variable.

Extensions not persisting after redeployment Ensure the /config volume is properly mounted to ../files/code-server-config. Extensions are stored in /config/extensions inside the container. Check that the volume mount is not empty after redeployment.

Terminal commands fail with "permission denied" Set SUDO_PASSWORD in the environment variables to enable sudo access in the integrated terminal. Verify PUID and PGID match the file ownership in your workspace: chown -R 1000:1000 ../files/code-server-config.

Git push fails with SSH errors Place your SSH keys in ../files/code-server-config/.ssh/ on the host (maps to /config/.ssh in the container). Set correct permissions: chmod 600 on private keys and chmod 700 on the .ssh directory.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about code-server in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running code-server.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.