Administrator Operations Guide

This guide covers the deployment and management of the DDEV Coder template for administrators.

Prerequisites

Before deploying this template, ensure the following are in place:

Coder Server

Setting up a new server? See the Server Setup Guide for step-by-step installation of Docker, Sysbox, and Coder.

Docker Host Infrastructure

Docker Registry Access

Local Tools

Building the Docker Image

The base image contains Ubuntu, Docker daemon, DDEV, Node.js, and essential development tools.

Using the Makefile

The Makefile automates all build and deployment tasks:

# Show available commands
make help

# Build image with cache
make build

# Build without cache (clean build)
make build-no-cache

# Push to registry
make push

# Build and push in one step
make build-and-push

# Test the built image
make test

# Show version info
make info

See image/README.md for details on customizing the Docker image.

Deploying the Template

Using the Makefile

# Push template only
make push-template-user-defined-web

# Full deployment (build image + push image + push template)
make deploy-user-defined-web

# Full deployment without cache
make deploy-user-defined-web-no-cache

Template Configuration

The template is defined in user-defined-web/template.tf. Key configuration parameters:

variable "workspace_image_registry" {
  default = "index.docker.io/ddev/coder-ddev"
}

variable "image_version" {
  default = "v0.1"  # Update this when releasing new image versions
}

variable "cpu" {
  default = 4  # CPU cores per workspace
}

variable "memory" {
  default = 8  # RAM in GB per workspace
}

variable "docker_gid" {
  default = 988  # Docker group ID (must match host)
}

To use a private registry:

  1. Update workspace_image_registry in template.tf
  2. Configure registry_username and registry_password variables
  3. Push template: coder templates push --directory user-defined-web user-defined-web --yes

Version Management

Version Files

The VERSION file in the root directory controls the image tag. The Makefile automatically copies it into the template directory before pushing, and template.tf reads it from there — no manual edits to template.tf are needed.

Releasing a New Version

# 1. Update VERSION file
echo "v0.7" > VERSION

# 2. Build, push image, and push template (VERSION is synced automatically)
make deploy-user-defined-web

# Or without cache for clean build
make deploy-user-defined-web-no-cache

Managing Workspaces

Creating Workspaces

Via Web UI:

  1. Log into Coder dashboard
  2. Click “Create Workspace”
  3. Select “user-defined-web” template
  4. Enter workspace name
  5. Configure parameters (optional: CPU, memory)
  6. Click “Create Workspace”

Via CLI:

# Create with defaults
coder create --template user-defined-web my-workspace --yes

# Create with custom parameters
coder create --template user-defined-web my-workspace \
  --parameter cpu=8 \
  --parameter memory=16 \
  --yes

Listing Workspaces

# List all workspaces
coder list

# List workspaces for specific template
coder list --template user-defined-web

# Show detailed workspace info
coder show my-workspace

Starting/Stopping Workspaces

# Stop workspace (saves state, stops billing)
coder stop my-workspace

# Start workspace
coder start my-workspace

# Restart workspace
coder restart my-workspace

Updating Workspaces

When you push a new template version, existing workspaces don’t automatically update.

To update a workspace to new template version:

# Update in place (preserves /home/coder)
coder update my-workspace

# Or from web UI: Click workspace → Update button

Notes:

Deleting Workspaces

# Delete workspace (warns if running)
coder delete my-workspace

# Force delete
coder delete my-workspace --yes

# Delete multiple workspaces
coder delete workspace1 workspace2 workspace3 --yes

Note: Deleting a workspace removes:

Template Updates

Updating Template Configuration

# 1. Edit template.tf
vim user-defined-web/template.tf

# 2. Push updated template
make push-template-user-defined-web

Updating Docker Image

# 1. Edit image/Dockerfile (if needed)
# 2. Increment version (template reads this automatically)
echo "v0.7" > VERSION

# 3. Build and deploy
make deploy-user-defined-web

# Users must rebuild workspaces to get new Docker image

Rolling Back

# Revert to previous template version
git checkout <previous-commit> user-defined-web/template.tf
coder templates push --directory user-defined-web user-defined-web --yes

# Users on old version are unaffected
# Users can update to rollback version via: coder update <workspace>

Backup and Maintenance

Workspace Data Backup

Each workspace stores persistent data in:

Backup strategy:

# Backup home directory
tar -czf workspace-backup.tar.gz /coder-workspaces/<owner>-<workspace>

# Backup Docker volume
docker run --rm \
  -v coder-<owner>-<workspace>-dind-cache:/source \
  -v $(pwd):/backup \
  ubuntu:24.04 \
  tar -czf /backup/docker-volume-backup.tar.gz -C /source .

# Restore Docker volume
docker volume create coder-<owner>-<workspace>-dind-cache
docker run --rm \
  -v coder-<owner>-<workspace>-dind-cache:/target \
  -v $(pwd):/backup \
  ubuntu:24.04 \
  tar -xzf /backup/docker-volume-backup.tar.gz -C /target

Template Versioning

Store template versions in git:

# Tag releases
git tag -a v0.1 -m "Release v0.1"
git push origin v0.1

# Track changes
git log --oneline user-defined-web/template.tf

Monitoring

Check workspace health:

# View workspace logs
coder ssh my-workspace -- journalctl -u coder-agent -f

# Check Docker daemon inside workspace
coder ssh my-workspace -- docker ps
coder ssh my-workspace -- docker info

# Check DDEV status
coder ssh my-workspace -- ddev list

Resource usage:

# Check workspace container resources
docker stats coder-<workspace-id>

# Check disk usage
df -h /coder-workspaces/
docker system df

Troubleshooting

See troubleshooting.md for detailed debugging procedures.

Quick checks:

# Template deployment failed
coder templates list  # Check if template exists
terraform validate    # Validate template syntax

# Workspace won't start
coder logs my-workspace           # View startup logs
docker logs coder-<workspace-id>  # View container logs

# Docker daemon issues
coder ssh my-workspace -- cat /tmp/dockerd.log
coder ssh my-workspace -- systemctl status docker

Security Considerations

Sysbox Runtime

Sysbox provides secure nested containers without privileged mode:

Security profiles in template.tf:

security_opt = ["apparmor:unconfined", "seccomp:unconfined"]

These are required for Sysbox functionality and are safer than --privileged.

User Isolation

Registry Security

Network Security

Best Practices

Resource Allocation

Monitor resource usage and adjust template defaults accordingly.

Template Naming

Image Management

Workspace Lifecycle

Documentation

Additional Resources