hoerdle/docs/DEPLOYMENT.md

Deployment Guide

Automated Deployment

Use the deployment script for zero-downtime deployments:

./scripts/deploy.sh

This script will:

1. Create a database backup
2. Pull latest changes from git
3. Fetch all git tags (for version display)
4. Build the new Docker image
5. Restart the container with minimal downtime
6. Clean up old images

Manual Deployment

If you need to deploy manually:

# Pull latest changes
git pull

# Fetch tags (important for version display!)
git fetch --tags

# Build and restart
docker compose build
docker compose up -d

Version Display

The app displays the current version in the footer. The version is determined as follows:

1. During Docker build: The version is extracted from git tags using git describe --tags --always
2. At runtime: The version is read from /app/version.txt and exposed via the /api/version endpoint
3. Local development: The version is extracted directly from git on each request

Building with a specific version

You can override the version during build:

docker compose build --build-arg APP_VERSION=v1.2.3

Troubleshooting

If the version shows as "dev" or "unknown":

1. Make sure git tags are pushed to the remote repository:

   git push --tags
   

2. On the deployment server, fetch the tags:

   git fetch --tags
   

3. Verify tags are available:

   git describe --tags --always
   

4. Rebuild the Docker image:

   docker compose build --no-cache
   docker compose up -d
   

Health Check

The container includes a health check that monitors the /api/daily endpoint. Check the health status:

docker ps

Look for the "healthy" status in the STATUS column.

Caddy Reverse Proxy (Optional - Production)

For production deployments with automatic SSL/TLS certificates, Caddy can be used as a reverse proxy. Caddy provides:

• Automatic Let's Encrypt certificates (including wildcard certificates)
• HTTP to HTTPS redirect
• Optimized settings for audio streaming and file uploads
• Support for both hoerdle.de and hördle.de (Punycode: xn--hrdle-jua.de)

Quick Start

1. Follow the setup guide: See CADDY_SETUP.md for detailed instructions
2. Configure environment variables: Add GoDaddy API credentials to your .env file
3. Start with Caddy:

   docker compose -f docker-compose.yml -f docker-compose.caddy.yml --profile production up -d
   

Without Caddy

If you don't want to use Caddy, you can deploy normally:

docker compose -f docker-compose.yml up -d

The application will still be accessible on port 3010, but you'll need to configure SSL/TLS separately (e.g., with nginx).

Caddy Troubleshooting

See CADDY_SETUP.md for detailed troubleshooting information.