Installation Guide

This guide provides detailed instructions for installing and configuring PuzzleSpring for both development and production environments.

Prerequisites

  • Docker Engine (version 20.10.0 or higher)
  • Docker Compose (version 2.0.0 or higher)
  • Git

Basic Installation

  1. Clone the repository: 
    git clone https://github.com/dlareau/puzzlespring.git
cd puzzlespring
  2. Copy the sample environment file: 
    cp sample.env .env
  3. Configure your environment variables in .env. At minimum, you need to set:
    • DJANGO_SECRET_KEY: A secure random string
    • DB_PASSWORD: Password for the PostgreSQL database
    • DOMAIN: Your domain name (use localhost for development)

To generate a secure Django secret key, you can use Python:

python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'

Copy the output into your .env file as the DJANGO_SECRET_KEY value.

Development Setup

For local development:

  1. Start the development server: 
    docker compose up -d
  2. Run the initial setup command: 
    docker compose exec app python manage.py initial_setup

  3. Follow the interactive prompts to create your superuser account

  4. Access the application at http://${DOMAIN}:${HTTP_PORT} (by default http://localhost:8000)

Production Deployment

For production environments:

  1. Configure your domain:
    • Set DOMAIN in .env to your actual domain name (e.g., puzzles.example.com)
    • Remove any port number from the domain to enable automatic SSL

Ensure you’ve set secure values for DJANGO_SECRET_KEY and DB_PASSWORD, and that DJANGO_ENABLE_DEBUG=False

  1. Start the application: 
    docker compose up -d
  2. Run the initial setup: 
    docker compose exec app python manage.py initial_setup
  3. Access your site at https://your-domain.com

The Caddy server will automatically obtain and manage SSL certificates for your domain.

Post-Installation

After installation, you should:

  1. Log in to the admin interface at /admin using your superuser account

  2. Configure In-App Settings through the admin interface

  3. Create your first hunt or import an existing hunt template

Troubleshooting

Common Issues

  1. SSL Certificate Issues
    • Ensure your domain is pointed to your server
    • Check that ports 80 and 443 are accessible
    • Verify DOMAIN doesn’t include a port number
  2. Static Files Missing
    • Run docker compose exec app python manage.py collectstatic

Checking Logs

To view logs for any service:

docker compose logs [service_name]

Available services:

  • app: Main application
  • db: Database
  • caddy: Web server
  • redis: Cache
  • pushpin: Real-time updates
  • huey: Background tasks

Next Steps

Customizing Static Files

To override or add custom static files:

  1. Create a custom/static directory in your project root
  2. Place your custom static files in this directory
  3. Restart the containers to apply changes: 
    docker compose restart app

The custom static directory is mounted as a volume, so changes will be reflected without rebuilding the container.

Customizing Templates

To override or customize templates:

  1. Create a custom/templates directory in your project root
  2. Mirror the template structure you want to override. For example: 
    custom/templates/
└── puzzlehunt/
    └── puzzle_base.html
  3. Files in this directory will take precedence over the default templates
  4. Restart the containers to apply changes: 
    docker compose restart app

The custom templates directory is mounted as a volume, so changes will be reflected without rebuilding the container.

When overriding templates, ensure you maintain the expected blocks and context variables. Refer to the Templates documentation for details.