Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Nov 2026
verified on Ubuntu 26.04 · Nov 2026Self-host Coder 2.38.6 (cloud development environments) with PostgreSQL on a 4 GB VPS — pinned tags, loopback-only port, Caddy HTTPS, creating the first owner from the CLI, a working Docker workspace, backups.
Coder is a platform for cloud development environments.
Administrators write workspace templates in Terraform; developers create
workspaces from them (here, Docker containers on the same server, but
upstream also ships Kubernetes and cloud-VM templates) and connect with a
browser IDE, VS Code, JetBrains or SSH. It is a Go control plane with a React
dashboard, state lives in PostgreSQL, and the code is licensed
AGPL-3.0 except the enterprise/ directory of the repository, which is
under a separate enterprise license (LICENSE.enterprise). Upstream's licensing page says some features are only
accessible with a Premium license (its example is AI Governance; see the
pricing page for the list); everything in this
guide runs without a license. It is rated 3 / 5 to deploy.
For a lighter, single-user alternative that only gives you VS Code in a browser, see code-server. For an AI agent that works inside a sandbox rather than a developer workspace, see OpenHands.
Security notes before you start. Two things matter:
/var/run/docker.sock into the Coder
container and adds the container to the host's docker group. Docker's own
documentation says "the docker group grants root-level privileges". Anyone
who compromises the Coder container, or who can edit a template (templates
are Terraform that drive the host's Docker daemon), can in effect become
root on the server. Run Coder on a server
that holds nothing else you care about, and give template-editing rights
only to people you would give root to.owner role. Coder
listens only on loopback until Caddy is started, so this guide creates the
owner from the command line, over loopback, before Caddy makes the site
public. Do not start Caddy first.Upstream's Docker install page asks for 2 CPU cores and 4 GB of memory free
on the machine; it publishes no per-workspace numbers. What we measured: on a
GCP e2-standard-2 (Ubuntu 26.04, Docker 29.9.3, November 2026) the stack, with one running Docker workspace and
nobody using it, settled at about 90-100 MB of RAM for Coder, 80 MB for
PostgreSQL, 13 MB for Caddy and 140 MB for the workspace container
(about 330 MB in all, by docker stats --no-stream, sampled over several
minutes from about 6 minutes after the stack came up and the workspace build finished).
Right after the template push and workspace build Coder was much higher:
about 430-450 MB for the first several minutes in two separate runs, so
plan for roughly 450 MB of Coder at busy moments. Docker
disk for the images in use was about 3.1 GB (Coder 879 MB, the starter
template's workspace image 1.52 GB, PostgreSQL 646 MB, Caddy 92 MB) plus
about 970 MB of volumes and 790 MB of container layers
(docker system df; the host also held an unrelated 9 GB image from earlier
tests, which we left out). Those numbers describe a nearly empty install with
one idle workspace; real development tools inside workspaces use far more.
Upstream's 4 GB floor is a sensible choice for that reason. Each workspace is
another container (plus its image) on the same host, so size the server for the workspaces you plan to run at once, not for Coder
alone.
Install Docker and the Compose plugin by following Docker and Compose on Ubuntu, and confirm the versions:
docker --version
docker compose version
Open SSH plus the two ports Caddy will use. Coder itself gets no public port:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force enable
Docker publishes container ports by editing the firewall directly, which
bypasses ufw rules. That is why the compose file below binds Coder's port to
127.0.0.1 instead of relying on ufw to block it.
Paid link — we earn a commission if you shop through it.
Coder's CODER_ACCESS_URL must be the external URL that users and
workspaces use to reach the server, and it must not be localhost. We use
the HTTPS address Caddy will serve in the next section. With no domain yet, an
sslip.io name resolves to your server's IP with no DNS setup, which is what
this guide uses so every command runs as written. Keep this shell session
open (or re-run the line) for the rest of the guide, and replace the value
with your real hostname when you have one:
DOMAIN="coder.$(curl -4s https://ifconfig.me).sslip.io"
echo "$DOMAIN"
Generate the database password and record the access URL and the docker
group's numeric id (the container runs as a non-root user and needs that
group to use the socket). The block only writes .env if it does not exist,
so re-running it cannot change the password under a live database:
mkdir -p ~/coder && cd ~/coder
if [ ! -f .env ]; then
echo "DB_PASSWORD=$(openssl rand -hex 16)" > .env
echo "DOCKER_GID=$(getent group docker | cut -d: -f3)" >> .env
echo "CODER_ACCESS_URL=https://$DOMAIN" >> .env
fi
chmod 600 .env
Now the compose file, based on the one in upstream's repository
(compose.yaml) with Coder's port bound to loopback and the images pinned:
cd ~/coder
cat > docker-compose.yml <<'EOF'
services:
coder:
image: ghcr.io/coder/coder:v2.38.6
restart: unless-stopped
ports:
- "127.0.0.1:7080:7080"
environment:
CODER_PG_CONNECTION_URL: postgresql://coder:${DB_PASSWORD}@database/coder?sslmode=disable
CODER_HTTP_ADDRESS: 0.0.0.0:7080
CODER_ACCESS_URL: ${CODER_ACCESS_URL}
group_add:
- "${DOCKER_GID}"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- coder_home:/home/coder
depends_on:
database:
condition: service_healthy
database:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_USER: coder
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: coder
volumes:
- coder_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U coder -d coder"]
interval: 5s
timeout: 5s
retries: 10
volumes:
coder_data:
coder_home:
EOF
CODER_PG_CONNECTION_URL points Coder at PostgreSQL (upstream's minimum is
13; if it is unset Coder downloads a built-in PostgreSQL and keeps it in its
config directory, which is not what you want on a server you back up).
CODER_HTTP_ADDRESS is where Coder listens inside the container; the
127.0.0.1: prefix on the published port keeps it off the public interface.
Upstream's compose file notes that the coder_home volume is not required in
production and that Coder can recreate the files it needs on restart.
Start the stack and wait for Coder's health endpoint on the loopback port:
cd ~/coder
docker compose up -d
out=000
for i in $(seq 1 60); do
out=$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:7080/healthz)
[ "$out" = "200" ] && break
sleep 3
done
docker compose ps
echo "coder healthz over loopback: $out"
[ "$out" = "200" ] || false
The first start runs the database migrations. Nothing is exposed yet: the only listener is on loopback.
At this point Coder listens only on 127.0.0.1, so nobody else can reach it,
and Caddy is not running yet. The deployment has no users, and whoever
completes first-user setup becomes the owner, so claim it now, before
Caddy makes the site public. The coder CLI is inside the image, so run it in
the container against the loopback address, with a generated password kept in
a file only you can read. The email below is a placeholder: use your own for a
real deployment. Do not request a trial license here
(--first-user-trial=false):
cd ~/coder
( umask 077; openssl rand -hex 16 > ~/coder/admin-password.txt )
docker compose exec -T coder /opt/coder login http://127.0.0.1:7080 \
--first-user-username admin \
--first-user-email admin@example.com \
--first-user-password "$(cat ~/coder/admin-password.txt)" \
--first-user-trial=false
docker compose exec -T coder /opt/coder users list
The first account has the owner role, and the session is saved inside the
container's coder_home volume, so later docker compose exec commands are
already signed in. Log in to the dashboard at your hostname with admin and
the password in ~/coder/admin-password.txt. Upstream recommends SSO with
multi-factor authentication for production (OIDC or GitHub; see its Users
page) instead of shared passwords.
Create an A record for your hostname (say coder.example.com) pointing at
the server and use that as CODER_ACCESS_URL in .env. The sslip.io name
from the previous section needs no DNS. Run Caddy as a container on the host
network. It obtains and renews a Let's Encrypt certificate on its own (see
Automatic HTTPS with Caddy) and proxies
to the loopback port:
mkdir -p ~/caddy
cat > ~/caddy/Caddyfile <<EOF
$DOMAIN {
reverse_proxy 127.0.0.1:7080
}
EOF
docker rm -f caddy >/dev/null 2>&1 || true
docker run -d --name caddy --restart unless-stopped --network host \
-v ~/caddy/Caddyfile:/etc/caddy/Caddyfile:ro -v caddy_data:/data caddy:2
That is the whole proxy configuration. Coder's workspace connections use
WebSockets, and Caddy's reverse_proxy performs the HTTP upgrade and tunnels
the connection with no extra directive; upstream's own Caddy example is the
same plain reverse_proxy. Check that HTTPS answers with a trusted
certificate, retrying while the certificate is issued:
out=000
for i in $(seq 1 24); do
out=$(curl -s -o /dev/null -w '%{http_code} %{ssl_verify_result}' "https://$DOMAIN/healthz") && [ "${out%% *}" = "200" ] && break
sleep 5
done
echo "coder over HTTPS and certificate check: $out"
[ "${out%% *}" = "200" ] || false
A second number of 0 means the certificate verified.
What about CODER_WILDCARD_ACCESS_URL? It is the optional wildcard
hostname (for example *.coder.example.com) under which Coder serves
workspace apps and forwarded ports on their own subdomains. Upstream says it
is necessary for port forwarding via the dashboard and for coder_apps that
run on an absolute path; web tools such as Vite, React and Next.js dev
servers, JupyterLab and RStudio need it. Setting it requires a wildcard DNS record and a TLS certificate that covers
the wildcard. The single-hostname Caddyfile above does not do that, so this
guide leaves it unset: SSH and the coder CLI do not need it, but the
dashboard's port-forwarding and subdomain-app features will not work until you
add it. Two ways to get the wildcard certificate: use a Caddy build with a DNS
provider plugin for your domain (DNS-challenge issuance), or follow upstream's
Caddy tutorial, which uses Caddy's on-demand TLS: a site block for
coder.example.com, *.coder.example.com with tls { on_demand }, plus a
global on_demand_tls { ask <url> } where the ask URL is an endpoint you
control that approves each hostname before Caddy requests a certificate for
it. On-demand needs the wildcard DNS record (*.coder.example.com pointing at
the server) and that endpoint; we did not test either option here. See upstream's
"Wildcard access URLs" page.
Now prove that workspaces work. With HTTPS up, initialise upstream's Docker starter
template inside the container, push it as a template named docker, and
create one workspace from it. Terraform downloads its providers from the
internet the first time (the provider release files are served from
github.com, and in our runs that download intermittently timed out from the
VM, so the push and the create are each wrapped in a short retry loop); allow a few minutes:
cd ~/coder
docker compose exec -T coder /opt/coder templates init --id docker /tmp/docker-template
ok=0
for i in 1 2 3; do
docker compose exec -T coder /opt/coder templates push docker -d /tmp/docker-template -y --message "docker starter" && { ok=1; break; }
echo "template push failed (attempt $i), retrying"; sleep 15
done
[ "$ok" = "1" ] || { echo "template push failed after 3 attempts"; false; }
ok=0
for i in 1 2 3; do
docker compose exec -T coder /opt/coder create ws1 --template docker -y --parameter 'jetbrains_ides=[]' </dev/null && { ok=1; break; }
echo "workspace create failed (attempt $i), retrying"; sleep 15
done
docker compose exec -T coder /opt/coder list
[ "$ok" = "1" ] || { echo "workspace create failed after 3 attempts"; false; }
The starter template includes a JetBrains module with a jetbrains_ides
list parameter. Its stored default is [] and it is not required, but
coder create still prompts for every non-ephemeral parameter on create
(upstream's cli/parameterresolver.go), so unattended it stops at an IDE
menu and hangs a script. Passing jetbrains_ides=[] selects none (choose IDEs
in the dashboard when you create real workspaces). Creating a workspace runs a Terraform dry run that downloads the providers
again, which is why it sits inside the same retry loop.
Check that the workspace container is up and that its agent connected back through the HTTPS access URL:
cd ~/coder
status=none
for i in $(seq 1 60); do
status=$(docker compose exec -T coder /opt/coder list -o json | python3 -c 'import sys,json; w=json.load(sys.stdin)[0]; print(w["latest_build"]["resources"][0]["agents"][0]["status"])' 2>/dev/null || echo none)
[ "$status" = "connected" ] && break
sleep 5
done
echo "workspace agent status: $status"
docker ps --filter name=coder- --format '{{.Names}} {{.Status}}'
[ "$status" = "connected" ] || false
connected means the agent inside the workspace container reached the control
plane over CODER_ACCESS_URL and the proxy, so the whole path works. The
workspace is a plain container on the host's Docker, started by Coder through
the socket.
Coder keeps its state in PostgreSQL: users, templates and template versions,
workspace records and settings; the restore test below shows that
workspaces can be rebuilt from it. That one database is what a backup must cover. Also keep
.env, docker-compose.yml and ~/caddy/Caddyfile (they are not in any
volume). Workspace containers are not backed up: they are recreated from
the template when a workspace is started. Workspace contents are not in
the database either: the Docker starter template keeps each workspace's home
directory in its own Docker volume on the host (docker volume ls shows
coder-<workspace id>-home), so back those volumes up separately if
developers keep work only there. The coder_home volume held only the CLI
session and Terraform caches in our install, and a restore with it wiped
needed nothing from it; Coder recreates it. Dump the
database with the stack running; pipefail makes a failed pg_dump fail the
step, and the last line checks the dump ends with PostgreSQL's completion
marker (a bare size check would pass on an empty gzip file):
cd ~/coder
set -o pipefail
mkdir -p ~/coder-backup
F=~/coder-backup/coder-$(date +%F).sql.gz
docker compose exec -T database pg_dump -U coder coder | gzip > "$F"
cp .env docker-compose.yml ~/caddy/Caddyfile ~/coder-backup/
ls -la ~/coder-backup
test -s "$F"
gzip -dc "$F" | tail -n 3 | grep -q 'PostgreSQL database dump complete'
set +o pipefail
Copy the archive off the server to object storage or another machine on a
schedule; the .env copy holds the database password, so keep it protected.
Upstream's upgrade page says to take a database snapshot before upgrading
because Coder does not support rollbacks. To check that a dump is usable, load
it into a scratch database in the running PostgreSQL and compare it with the
live one:
cd ~/coder
docker compose exec -T database createdb -U coder coder_restore_test
gunzip -c ~/coder-backup/coder-$(date +%F).sql.gz | docker compose exec -T database psql -q -v ON_ERROR_STOP=1 -U coder coder_restore_test >/dev/null
for d in coder coder_restore_test; do
docker compose exec -T database psql -U coder "$d" -Atc "select current_database(), (select count(*) from users), (select count(*) from templates), (select count(*) from workspaces)"
done
docker compose exec -T database dropdb -U coder coder_restore_test
The two lines should match. To restore for real, bring up an empty stack: take
docker-compose.yml and the Caddyfile from the backup, and regenerate
DOCKER_GID and CODER_ACCESS_URL in .env for the new server (the backed
up values are the old host's docker group id and old address; the sslip.io
name embeds the old IP). Then start only database and wait until it is
healthy (--wait; otherwise psql can hit a database that is still
initialising and Coder would start empty), load the dump with
ON_ERROR_STOP so any error aborts, and only then start coder:
cd ~/coder
docker compose up -d --wait database
gunzip -c ~/coder-backup/coder-DATE.sql.gz | docker compose exec -T database psql -v ON_ERROR_STOP=1 -U coder coder
docker compose up -d
We tested this whole procedure on the verification VM, outside the scripted
pass because it destroys the stack: with the workspace running we removed the
workspace container and its volume and ran docker compose down -v (which
deletes coder_data and coder_home), regenerated DOCKER_GID, ran the
block above, and then logged in with the saved owner password (it worked, with
the owner role), found the docker template and the ws1 workspace record
in place, and coder restart ws1 recreated the workspace container from the
restored state and its agent reconnected. The workspace's home volume was not
restored (it came back empty), which is the volume backup mentioned above.
An untested backup is a guess, so restore into a throwaway server now and then. Upstream's docs list database encryption of external tokens as a Premium feature; if you use it, the encryption keys are not in the database, so back them up too.
Take the backup above first: upstream states Coder does not support
rollbacks. Upstream's upgrade page says to reinstall by your original method,
and for docker compose that is pulling the new image and recreating the
coder container; migrations run on start. Upstream's release page publishes
channels: when we wrote this, 2.38 was listed as Stable (v2.38.6 is the
latest 2.38 patch), 2.39 as Mainline, and 2.37 as Security Support
(security fixes only). 2.34 and 2.29 were listed as Extended Support Release
(critical bugfixes and security patches), and 2.35 and 2.36 as not supported.
Upstream recommends planning upgrades for off-peak hours and notes that a
larger version jump runs more migrations. Move the pin yourself rather than
tracking latest:
cd ~/coder
sed -i 's|coder:v2.38.6|coder:NEW_VERSION|' docker-compose.yml
docker compose pull coder
docker compose up -d coder
The PostgreSQL tag is a separate decision: moving majors is a dump and restore, not a new image.
permission denied on /var/run/docker.sock in the Coder logs. The
DOCKER_GID in .env is not the host's docker group. Re-check with
getent group docker | cut -d: -f3, fix .env, and run docker compose up -d
(upstream's Docker page covers the --group-add fix under "I cannot add Docker templates"; its "permission denied" entry only links Docker's post-install page).
A workspace build fails or the agent never connects. The workspace must
reach CODER_ACCESS_URL. It cannot be localhost/127.0.0.1, and the name
must resolve from inside a container. Look at docker compose logs coder and
the build log in the dashboard.
Port 7080 is reachable from the internet. The port line lost its
127.0.0.1: prefix. Fix the compose file, docker compose up -d, then check
that ss -tln | grep 7080 shows 127.0.0.1.
Certificate never issues. That is a Caddy and DNS problem rather than a
Coder one: confirm the A record resolves and that ports 80 and 443 are
reachable. Look at docker logs caddy.
Forgot the owner password. Upstream documents coder reset-password <username>, which only works on the host running the control plane; here that
is docker compose exec coder /opt/coder reset-password admin.
You are done when https://coder.example.com/healthz answers 200 with a
valid certificate, port 7080 is bound only to 127.0.0.1, the ws1 workspace
shows an agent in the connected state, and a database dump is landing off the
server. Delete the test workspace when you no longer need it
(docker compose exec coder /opt/coder delete ws1 -y).
From here, add your own templates (start from the starter you pushed), set up SSO, and decide whether you need the wildcard access URL. If you only want a browser editor, code-server is far lighter.
We estimate about 40 minutes of hands-on time for "How to Deploy Coder on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy Coder on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Nov 2026).