jared
/
server-ovh-prod-01-main
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
server-ovh-prod-01-main/docs/configuration-reference.md

7.6 KiB
Raw Permalink Blame History

Configuration Reference

This document catalogs all configuration templates and files available in the configs/ directory for deploying services on systems-prod-01.

Template Overview

Template Purpose Service Type
wordpress-template.yml WordPress with MariaDB WordPress Site
invoiceninja-template.yml Invoice Ninja invoicing app Web Application
traefik/docker-compose.yml Traefik reverse proxy Infrastructure

Traefik Configuration

Location

configs/traefik/

Files

  • docker-compose.yml - Traefik container orchestration
  • traefik.yml - Static configuration (entrypoints, providers, API)
  • dynamic.yml - Dynamic configuration (routers, services, middlewares)

When to Use

  • Setting up a new server from scratch
  • Reconfiguring the reverse proxy
  • Adding global middlewares or routes
  • Reference for Traefik label syntax

Key Features

  • Automatic SSL with Let's Encrypt
  • HTTP to HTTPS redirect
  • Docker provider for automatic service discovery
  • Dashboard on port 8080 with basic auth

WordPress Template

Location

configs/wordpress-template.yml

Supporting Files

  • configs/wordpress.env.example - Environment variables template
  • configs/uploads.ini - PHP upload size configuration
  • configs/my.cnf - MariaDB optimization

When to Use

  • Migrating a WordPress site from another server
  • Deploying a new WordPress site
  • Reference for WordPress + Traefik integration

Key Features

  • WordPress 6.7 with Apache
  • MariaDB 10.11 (LTS, WordPress-compatible)
  • Traefik integration with automatic SSL
  • Health checks for database
  • Separate internal network for database

Usage Example

# 1. Create service directory
ssh jared@15.204.247.153 "mkdir -p ~/services/SITENAME"

# 2. Copy and adapt template
cp configs/wordpress-template.yml /tmp/docker-compose.yml
# Edit with your site details

# 3. Deploy to server
scp /tmp/docker-compose.yml jared@15.204.247.153:~/services/SITENAME/
ssh jared@15.204.247.153 "cd ~/services/SITENAME && docker compose up -d"

Template Customization Checklist

  • Replace SITENAME with actual service name
  • Update domain names in Traefik labels
  • Set database credentials
  • Configure volume paths
  • Adjust memory/resource limits if needed
  • Verify network names match server setup

Invoice Ninja Template

Location

configs/invoiceninja-template.yml

Supporting Files

  • configs/invoiceninja.env.example - Environment variables
  • configs/invoiceninja-nginx.conf - Nginx configuration

When to Use

  • Deploying Invoice Ninja for invoicing/billing
  • Reference for PHP-FPM + Nginx + MySQL setup
  • Multi-container application pattern

Key Features

  • Invoice Ninja v5
  • Nginx + PHP-FPM architecture
  • MySQL database with health checks
  • Persistent storage for invoices and uploads
  • Traefik integration

Configuration Patterns

Standard Service Structure

All services follow this pattern:

services:
  app:
    image: application:latest
    restart: unless-stopped
    networks:
      - traefik      # External access
      - internal     # Backend communication
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.SERVICENAME.rule=Host(`domain.com`)"
      - "traefik.http.routers.SERVICENAME.entrypoints=websecure"
      - "traefik.http.routers.SERVICENAME.tls.certresolver=letsencrypt"
    volumes:
      - ./data:/var/www/html

networks:
  traefik:
    external: true
  internal:
    external: true

Traefik Labels Guide

Basic routing:

- "traefik.enable=true"
- "traefik.http.routers.SERVICENAME.rule=Host(`domain.com`)"
- "traefik.http.routers.SERVICENAME.entrypoints=websecure"
- "traefik.http.routers.SERVICENAME.tls.certresolver=letsencrypt"

Multiple domains:

- "traefik.http.routers.SERVICENAME.rule=Host(`domain.com`) || Host(`www.domain.com`)"

Custom port (if app doesn't use 80):

- "traefik.http.services.SERVICENAME.loadbalancer.server.port=8080"

Basic auth middleware:

- "traefik.http.routers.SERVICENAME.middlewares=auth"
- "traefik.http.middlewares.auth.basicauth.users=user:$$apr1$$hashed$$password"

Environment Variable Management

Best Practices

  1. Never commit secrets - Use .env files (gitignored)
  2. Use example files - Provide .env.example with placeholders
  3. Document required vars - List all necessary environment variables
  4. Escape dollar signs - In docker-compose.yml, use $$ for literal $

Example .env File Structure

# Database Configuration
DB_NAME=myapp_db
DB_USER=myapp_user
DB_PASSWORD=CHANGE_ME_STRONG_PASSWORD

# Application Settings
APP_NAME=MyApplication
APP_URL=https://myapp.com
APP_DEBUG=false

# Email Configuration (if needed)
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=user@example.com
MAIL_PASSWORD=CHANGE_ME

Creating Custom Templates

When creating a new service template:

  1. Start with a working configuration from existing templates
  2. Document all required changes in comments
  3. Include health checks where possible
  4. Use standard network pattern (traefik + internal)
  5. Follow naming conventions (lowercase, hyphens)
  6. Test thoroughly before documenting

Template File Naming

  • SERVICETYPE-template.yml - Docker Compose template
  • SERVICETYPE.env.example - Environment variables
  • SERVICETYPE-config-file - Additional config files

Docker Compose Tips

Volume Management

Bind mounts (for configs):

volumes:
  - ./config.php:/var/www/html/config.php:ro

Named volumes (for databases):

volumes:
  - db_data:/var/lib/mysql

volumes:
  db_data:

Health Checks

Web application:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost/health"]
  interval: 30s
  timeout: 10s
  retries: 3

Database:

healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
  interval: 30s
  timeout: 10s
  retries: 5

Resource Limits

deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G
    reservations:
      cpus: '0.5'
      memory: 512M

Network Configuration

Existing Networks

The server has two pre-configured Docker networks:

  • traefik (172.20.0.0/16) - External-facing services
  • internal (172.21.0.0/16) - Backend services

When to Create New Networks

Generally, use existing networks. Create a new network only when:

  • Service requires strict isolation
  • Complex multi-container setup needs dedicated network
  • Testing/development environment separation

Troubleshooting Configuration Issues

Template Not Working

# Validate docker-compose syntax
docker compose -f template.yml config

# Check for common issues
# - Indentation (YAML is space-sensitive)
# - Missing quotes around special characters
# - Incorrect network references
# - Typos in service names

Traefik Not Routing

# Check container is on traefik network
docker inspect CONTAINER_NAME | grep Networks -A 10

# Verify Traefik labels
docker inspect CONTAINER_NAME | grep traefik.

# Check Traefik dashboard
# https://traefik.hyperthrive.app

Environment Variables Not Loading

# Verify .env file exists in same directory as docker-compose.yml
ls -la ~/services/SERVICENAME/.env

# Check variable interpolation
docker compose config

See Also