A Flask web application for managing and browsing a gaming database, containerized with Docker and powered by PostgreSQL. Features a secure HTTPS reverse proxy via Nginx, Redis caching, user authentication, and AI-powered game info via the Anthropic Claude API.
- Overview
- Tech Stack
- Project Structure
- Prerequisites
- Getting Started
- Configuration
- Database Preparation
- Running the App
- Accessing the App
- Authentication
- Database
- Redis Caching
- AI Features
- Stopping the App
- Development
- Security Notes
- Troubleshooting
This application provides a full CRUD interface for managing a gaming library database. It supports browsing, filtering, sorting, and editing games, platforms, perspectives, and category tags. The app is served over HTTPS through an Nginx reverse proxy, uses Redis for caching, requires login authentication, and integrates with the Anthropic Claude API for AI-generated game information.
| Layer | Technology |
|---|---|
| Backend | Python / Flask |
| Database | PostgreSQL 16 |
| ORM | SQLAlchemy |
| Templating | Jinja2 |
| Authentication | Flask-Login |
| Caching | Redis 7 |
| Reverse Proxy | Nginx (HTTPS) |
| AI Integration | Anthropic Claude API |
| Container | Docker / Compose |
simpleFlaskWebApp/
├── app/
│ ├── Dockerfile
│ ├── app.py
│ ├── requirements.txt
│ └── templates/
│ ├── base.html
│ ├── login.html
│ ├── index.html
│ ├── view_game.html
│ ├── game_info.html
│ ├── create_game.html
│ ├── edit_game.html
│ ├── search.html
│ ├── timeline.html
│ ├── platforms.html
│ ├── create_platform.html
│ ├── edit_platform.html
│ ├── perspectives.html
│ ├── create_perspective.html
│ ├── edit_perspective.html
│ ├── tags.html
│ ├── create_tag.html
│ ├── edit_tag.html
│ ├── comments.html
│ └── stats.html
├── nginx/
│ ├── Dockerfile
│ └── nginx.conf
├── utils/
│ ├── assets/
│ ├── db_struct.sql
│ ├── deploy_to_EC2.md
│ └── ...
├── docker-compose.yaml
├── .env
├── .env.example
├── .gitignore
└── readme.md
Make sure you have the following installed:
- Docker (v20+)
- Docker Compose (v2+)
Verify your installation:
docker --version
docker compose versiongit clone https://github.com/thjunge11/simpleFlaskWebApp.git
cd simpleFlaskWebAppcp .env.example .envEdit .env with your preferred values:
nano .env# Once — create the shared network
docker network create proxy_net
# Start nginx (can stay running permanently)
docker compose -f docker-compose.nginx.yaml up -d
# Start the app stack
docker compose up -dAll configuration is handled through environment variables. Create a .env file in the root of the project:
# Database Configuration
DB_HOST=db
DB_NAME=gaming
DB_USER=postgres
DB_PASS=your_secure_password_here
# Flask
SECRET_KEY=your_flask_secret_key_here
# Authentication
LOGIN_USERNAME=admin
LOGIN_PASSWORD=your_login_password_here
# Redis (optional overrides; defaults match docker-compose)
REDIS_HOST=redis
REDIS_PORT=6379
# Anthropic Claude AI
ANTHROPIC_API_KEY=your_anthropic_api_key_here
CLAUDE_MODEL=claude-3-5-haiku-20241022DB_HOST=db
DB_NAME=gaming
DB_USER=postgres
DB_PASS=changeme
SECRET_KEY=changeme
LOGIN_USERNAME=admin
LOGIN_PASSWORD=changeme
REDIS_HOST=redis
REDIS_PORT=6379
ANTHROPIC_API_KEY=
CLAUDE_MODEL=claude-3-5-haiku-20241022
⚠️ Never commit your.envfile to version control. It is already included in.gitignore.
The PostgreSQL database structure can be set up with the SQL script found in utils/db_struct.sql.
docker compose up --builddocker compose up --build -ddocker compose up --builddocker compose up| Service | URL |
|---|---|
| Web App | https://localhost |
| Web App (HTTP, redirects to HTTPS) | http://localhost |
| PostgreSQL | localhost:5435 |
| Redis | localhost:6379 |
Traffic is served over HTTPS via the Nginx reverse proxy. HTTP requests on port 80 are automatically redirected to HTTPS on port 443. The self-signed certificate generated at build time will trigger a browser warning — this is expected for local/dev use.
The PostgreSQL port is mapped to
5435(instead of the default5432) to avoid conflicts with any local PostgreSQL installation.
psql -h localhost -p 5435 -U postgres -d gamingOr using a GUI tool like DBeaver, TablePlus, or pgAdmin:
Host: localhost
Port: 5435
Database: gaming (or your DB_NAME value)
User: postgres (or your DB_USER value)
Password: your_secure_password_here
The app requires a login to access any page. Credentials are configured via environment variables:
LOGIN_USERNAME=admin
LOGIN_PASSWORD=your_login_password_here- Visit https://localhost — you will be redirected to the login page automatically.
- After logging in, you will be redirected back to the originally requested page.
- Use the logout link in the navigation bar to end your session.
The PostgreSQL database runs in a separate container with:
- Persistent storage via a named Docker volume (
postgres_data_volume). Your data survives container restarts. - Health checks to ensure the database is ready before the web app starts.
- Automatic initialization on first run.
docker compose psdocker compose exec db psql -U postgres -d gamingdocker compose exec db pg_dump -U postgres gaming > backup.sqlcat backup.sql | docker compose exec -T db psql -U postgres -d gamingRedis is used to cache frequently accessed data and improve response times. It runs as a separate container (redis:7-alpine) with:
- Persistent storage via a named Docker volume (
redis_data_volume). - Health checks to ensure Redis is ready before the web app starts.
docker compose logs -f redisdocker compose exec redis redis-cliThe app integrates with the Anthropic Claude API to provide AI-generated game information. Set your API key and preferred model in .env:
ANTHROPIC_API_KEY=your_anthropic_api_key_here
CLAUDE_MODEL=claude-3-5-haiku-20241022If ANTHROPIC_API_KEY is not set, AI-powered features will not be available but the rest of the app will work normally.
docker compose downdocker compose down -v# All services
docker compose logs -f
# Web app only
docker compose logs -f web
# Database only
docker compose logs -f db
# Nginx only
docker compose logs -f nginx
# Redis only
docker compose logs -f redisdocker compose restart webdocker compose exec web bash- Add the package to
app/requirements.txt - Rebuild the container:
docker compose up --build- Change the default
DB_PASSandLOGIN_PASSWORDto strong values before deploying. - Generate a secure Flask
SECRET_KEY:python -c "import secrets; print(secrets.token_hex(32))" - Never expose the database port (
5435) or Redis port (6379) publicly in production. - The Nginx container generates a self-signed TLS certificate at build time (valid for localhost/dev). For production, replace it with a certificate from a trusted CA (e.g., Let's Encrypt).
- Keep your
ANTHROPIC_API_KEYsecret and never commit it to version control.
The web service waits for the database health check to pass before starting. If it still fails:
# Check database logs
docker compose logs db
# Check if database is healthy
docker compose psThe web service also waits for the Redis health check. Check Redis logs:
docker compose logs redisIf port 80, 443, or 5435 is already in use, change the mapping in docker-compose.yaml:
ports:
- "8080:80" # Change 80 to another port
- "8443:443" # Change 443 to another portThe Nginx container uses a self-signed certificate generated at build time. This is expected for local development. Accept the warning to proceed.
Make sure you are not using docker compose down -v, as the -v flag removes volumes and all stored data.
docker compose down -v
docker compose up --buildThis project is licensed under the MIT License.