Docker Local Deployment

Prerequisites

Before deploying locally, ensure you have:

• Docker Desktop installed and running (version 20.10+)
• Git for cloning the repository
• Caddy network created (docker network create caddy)
• Text editor for configuration (VS Code, vim, etc.)

docker --version
# Expected: Docker version 20.10.0 or higher

docker compose version
# Expected: Docker Compose version v2.0.0 or higher

Step 1: Clone the repository

Clone your installation repository to your local machine:

# Clone the repository
git clone https://github.com/your-org/your-installation.git

# Navigate into the directory
cd your-installation/website

Note: The website/ subdirectory contains the Astro application and Docker configuration.

Step 2: Configure environment

Create a .env file with development settings:

# Development mode settings
ATELIER_MODE=dev
NODE_ENV=development

# Enable hot reload
ENABLE_HMR=true

# Ambient effects (optional)
AMBIENT_EFFECTS_ENABLED=true
AMBIENT_INTENSITY=medium

# Docker configuration
COMPOSE_PROJECT_NAME=your-installation-dev
PUBLIC_DOMAIN=localhost

# Debug settings
DEBUG=true
LOG_LEVEL=info

Step 3: Start services

Use the provided atelier.sh script or Docker Compose directly:

# Start in development mode
./atelier.sh dev

# This runs:
# docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

# Start with both base and development overrides
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

# Start in detached mode (runs in background)
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

First run: Expect 2-5 minutes for initial build. Subsequent starts are faster (~30 seconds).

Step 4: Verify deployment

Check that services are running and accessible:

docker compose ps

# Expected output:
# NAME                    STATUS
# your-installation-web   Up (healthy)

# Open in browser
open http://localhost:4321

# Or with curl
curl -I http://localhost:4321

# Expected: HTTP/1.1 200 OK

# View logs (follow mode)
docker compose logs -f

# View only web service logs
docker compose logs -f web

# Exit logs: Ctrl+C

Step 5: Test hot reload

Verify hot module reload is working:

1. 1. Open src/pages/index.astro in your editor
2. 2. Change the heading text
3. 3. Save the file
4. 4. Watch browser auto-refresh (2-3 seconds)

Not working? Check that ENABLE_HMR=true in .env and restart containers.

Managing the deployment

Common operations for local development:

# Stop containers (keeps them)
docker compose stop

# Stop and remove containers
docker compose down

# Stop, remove, and clean volumes
docker compose down -v

# Restart without rebuild
docker compose restart

# Restart with rebuild (after dependency changes)
docker compose up --build -d

# All services, follow mode
./atelier.sh logs

# Specific service
docker compose logs -f web

# Last 100 lines
docker compose logs --tail=100

# Stop, clean, and rebuild from scratch
./atelier.sh clean
./atelier.sh dev

# Or manually:
docker compose down -v
docker compose build --no-cache
docker compose up -d

Common issues

# Find process using port 4321
lsof -i :4321

# Kill the process (use PID from above)
kill -9 <PID>

# Or change port in docker-compose.dev.yml

docker network create caddy

# Remove node_modules volume
docker compose down -v

# Rebuild without cache
docker compose build --no-cache

# Start fresh
docker compose up -d

Next steps

Your local installation is running. Now you can: