Practical Python Code Adventure v2

🌐 Live at: https://adventure.practicalpython.org

Version 2 of Code Adventure brings a fully modular backend, a redesigned user experience, and flexible setup options for new or returning deployments.

The project is a series of interactive coding challenges (each with two parts), inspired by Advent of Code, built for the Practical Python Discord community. Challenges are now organized into yearly collections of 10, with a new set released each year.

All previous features have been preserved and improved, with better code structure, usability, and deployment options.

---

Key Updates in Version 2

• Modular Backend – Blueprints, services, and templating are now separated for clean, maintainable code.
• Updated Database – New PostgreSQL schema for version 2 challenges, with migration support from version 1.
• Smart Setup Options – setup.py recognizes whether to start fresh or carry over progress from version 1.
• Redesigned UX – Clearer layout, more eye-catching style, and expanded site content.
• Submission Cooldown - Server-side timer that prevents repeated submissions and discourages brute-force guessing.
• Challenge Organization – Puzzle inputs and media now structured for multiple years, simplifying future expansion.
• Improved Admin Dashboard – Modular routes and updated UI for managing users, challenges, sponsors, and releases.

---

Tech Stack

• 
• 
• 
• 
• 
• 
• 

---

Getting Started

Prerequisites

• Python 3.10+
• Docker & Docker Compose
• PostgreSQL (local or Docker-based)

⚠️ Python 3.10+ is required due to uv dependency management.

---

Environment Variables

Create a .env file in the project root (you can copy .env.EXAMPLE and fill in the values):

# PostgreSQL
POSTGRES_USER="postgres"
POSTGRES_PASSWORD="postgres"
POSTGRES_SERVER="postgres"
POSTGRES_PORT="5432"
DATABASE_NAME="YOUR_DB_NAME"

# Flask
FLASK_PORT=5000
FLASK_ENV="production"  # or  development
SECRET_KEY="Something_secret_goes_here"

# Discord
DISCORD_ADMIN_USER_ID="YOUR_ADMIN_ID"  # Used in entrypoint.sh
DISCORD_REDIRECT_URI="BASE_URL_HERE/callback"
DISCORD_CLIENT_ID="YOUR_CLIENT_ID"
DISCORD_CLIENT_SECRET="YOUR_CLIENT_SECRET"
DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

# Latest Year
YEAR=2026
KEY2025="KEY_HERE"
KEY2026="DIFFERENT_KEY_HERE"
# Add keys for other released years as needed

POSTGRES_* variables / DATABASE_NAME – DB credentials and host info.

FLASK_PORT – Port Flask runs on (default 5000).
FLASK_ENV – Set to development or production. SECRET_KEY – Used for securely signing application data and tokens.

DISCORD_ADMIN_USER_ID – Your Discord user ID for admin dashboard access.
DISCORD_* tokens – OAuth2 credentials for authentication and bot access.

YEAR – Latest challenge year to include (starting from 2025). Must not exceed released years.
KEY#### – Required key to access each year’s challenge and solution data to fill the DB.

To obtain KEYs, contact the project owner via Discord or by email.

---

Local Development

1. Clone the repository:

git clone https://github.com/JefeThePug/Zorak-Coding-Challenges.git
cd Zorak-Coding-Challenges

2. Install dependencies with uv:

uv sync --frozen --no-dev

3. Copy the .env.EXAMPLE file and fill in your values in the .env file:

cp .env.EXAMPLE .env

4. Run the initial setup:

python setup.py

5. Start the application:

python -m app.run

6. Access the app: http://localhost:5000

---

Running with Docker

1. Copy the example files and fill in your values:

cp .env.EXAMPLE .env
cp docker-compose.override.EXAMPLE.yml docker-compose.override.yml

docker-compose.override.yml enables hot-reload via the Flask dev server — edits to app/ are reflected instantly without rebuilding.

2. Run initial DB setup (first time only):

docker compose run --rm api uv run python setup.py

3. Build and start containers:

docker compose up --build

4. Access the app: http://localhost:5000

The Flask app connects to PostgreSQL using the hostname defined in POSTGRES_SERVER in your .env.

To run in production mode locally (gunicorn, no hot-reload), bypass the override:

docker compose -f docker-compose.yml up --build

---

Usage Overview

• Login – Authenticate via Discord to track progress.
• Challenges – Access version 2 challenges, each with two parts.
• Submit Solutions – Correct answers update progress and unlock discussion threads.
• Admin Tools – Modular dashboard for managing users, challenges, sponsors, and releases.

---

Code Structure Highlights

• app/blueprints/ – Routes organized by functionality: auth, challenge, admin, main, errors.
• app/services/ – Backend services for cooldowns, progress, and Discord notifications.
• app/templating/ – Global functions and utilities for rendering templates.
• setup.py & update_from_2025.py – Setup a blank DB or migrate from version 1.
• app/static/ & app/templates/ – Organized media and templates for multiple years, with year-specific style overrides.

---

Admin Dashboard

The admin dashboard allows easy management of Discord channel assignment, user progress, challenge content, and sponsor info. Here's a quick look:

↗️ Looping demo of the admin dashboard showing user and challenge management.

---

Sponsorship

Version 2 now supports sponsorship.

Sponsorship helps maintain the server, fund new challenges, and support ongoing development.

Individuals or companies can support the project financially. Sponsors are acknowledged on the site and help maintain and expand new challenges, infrastructure, and features. Contact the project owner for details on sponsoring.

---

Contributing

Contributions can include:

• Providing new challenge ideas
• Providing feedback or suggestions on frontend UX
• Updating backend services
• Discovering / fixing bugs
• Improving documentation

I am also looking for volunteers to help grow this project by:

• Beta testing new challenges
• Design themed illustration for the landing page images

Beta testers and illustrators will be acknowledged on the website

---

License

Open-source, intended for educational and community-building use.

---

Acknowledgments

• Inspired by Advent of Code
• Built for the Practical Python Discord
• Thanks to community members who tested and provided feedback for version 2.
  Individual credit is acknowledged on the website.