Bunkercaching

Bunkercaching is a small web application for exploring and logging Czech bunkers/fortifications. It consists of a Python FastAPI backend connected to a MariaDB database and a static frontend built with plain HTML/CSS/JavaScript using Leaflet for maps.

This README documents the current state of the project, how to run it locally.

Stack

• Backend: Python, FastAPI
• Database: MariaDB (MySQL-incompatible)
• Auth: Cookie-based JWT via python-jose
• Config: .env loaded via python-dotenv
• Frontend: Static HTML/CSS/JS, Leaflet map library
• Package manager(s):
  • Python: requirements.txt or pyproject.toml for uv

Project Structure

./
├─ backend/
│  ├─ main.py              # FastAPI application with auth and data endpoints
│  ├─ dbh.py               # MariaDB connection using env vars via python-dotenv
│  ├─ tokens.py            # JWT creation/validation
│  ├─ generator.py         # 
│  └─ dbupload.py          # Utility to import bunkers/ropíky into DB from data files
├─ web/
│  ├─ map/                 # Map UI (Leaflet) — entry: web/map/index.html
│  ├─ auth/                # Authentication-related JS
│  ├─ about/               # Static content
│  └─ data/                # Static data (images, logos, geodata)
├─ logo                    # Contains logos
├─ *.sql                   # SQL schema/data files (bunkry.sql, ropiky.sql, users.sql, logs.sql)
├─ Dockerfile
├─ docker-compose.yml
├─ docker.env              # Environment variables for Docker (not committed)
└─ README.md

Requirements

• Python 3.10+
• MariaDB server 10.x+
• Python packages: see requirements.txt or pyproject.toml

Install with pip:

python -m venv .venv                   # Create the virtualvenv
pip install -r requirements.txt        # Install the packages

Install with uv:

uv venv                                # Create the uv virtualenv
uv sync                                # Download all of the dependencies

Environment Variables

Backend reads DB connection from .env via backend/dbh.py:

DB_USER=
DB_PASSWORD=
DB_HOST=localhost
DB_NAME=

JWT configuration in backend/tokens.py is configurable via environment variables:

JWT_SECRET=
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=120

An example file is provided as example.env.

Database

Schema/data files are provided in the project root:

• bunkry.sql
• ropiky.sql
• users.sql
• logs.sql There is also some data about ropiky and bunkry
• backend/ropiky.json
• backend/bunkers.json

You can import the schema and populate the data of your MariaDB instance, e.g.:

python -m backend.full_db_init

Note: This also creates a new database bunkercaching

CORS configuration

The API enables CORS via FastAPI's CORSMiddleware. Configure allowed origins by environment variables (loaded from .env):

• CORS_ALLOW_ORIGINS — comma‑separated list of exact origins (default: http://localhost:8080)
• CORS_ALLOW_ORIGIN_REGEX — optional regex to match origins; if set, it overrides the list

Examples:

1. Allow a couple of sites during development:

CORS_ALLOW_ORIGINS=http://localhost:63342,http://127.0.0.1:8080,https://example.com

2. Allow requests from any http/https origin that is a public IP (optionally with a port):

CORS_ALLOW_ORIGIN_REGEX=^https?://(\d{1,3}\.){3}\d{1,3}(:\d+)?$

Security notes:

• You cannot use * for origins; prefer explicit lists or a carefully crafted regex.
• A very permissive regex can expose your API to the public internet. Use with caution and consider authentication and rate limiting.

Running Locally

1. Create and populate a Python virtual environment, then install dependencies:

With python virtualvenv

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

With uv:

uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv sync

2. Create a .env file in the project root with DB credentials:

DB_USER=your_user
DB_PASSWORD=your_password
DB_HOST=localhost
DB_NAME=your_database

3. Initialize the database using the backend/full_db_init.py:

python -m backend.full_db_init

4. Start the server (FastAPI app is defined in backend/main.py as app):

python -m uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

By default, CORS is configurable via environment variables. If you do nothing, it allows http://localhost:8000. See CORS configuration below.

Running with Docker

Docker Compose runs both the app and a MariaDB container. The database is initialized automatically on first start via backend/dbh.py.

Setup

1. Make sure you have docker running.

2. Build and start:

docker compose up --build

The app will be available at http://localhost:8000.

Subsequent starts

docker compose up

Stopping

docker compose down

Warning: docker compose down -v will delete the MariaDB volume and all data including users.

Manual backup

To back up the users and logs tables:

docker exec bunkercaching-db mariadb-dump -u root -pyour_root_password bunkercaching users logs > backup.sql

Notes

• docker.env is used exclusively by Docker and is not read by the Python app during local development.
• .env is excluded from the Docker image via .dockerignore.
• Database data is persisted in a named Docker volume (mariadb_data).

Admin Dashboard

• You can get an admin dashboard, but currently the only way is to change the role of the user form user to admin in the database. You can do this by running the following SQL command:

UPDATE users SET role='admin' WHERE username='your_username';

And here is a full docker command

docker exec bunkercaching-db mariadb -u root -proot_pwd bunkercaching -e "UPDATE users SET role='admin' WHERE username='your_username';"

API Overview of the uvicorn server

• GET / — Frontend
• GET /api/ — simple HTML landing page for the API
• POST /api/login — form fields: username, password, remember; sets JWT cookie on success
• POST /api/signup — form fields: username, email, password, confirm_password
• POST /api/me — returns current user (requires valid cookie token)
• POST /api/logout — clears auth cookie
• GET /api/ropiky?lat_one=...&lng_one=...&lat_two=...&lng_two=... — returns ropíky in a bounding box
• GET /api/bunkry?lat_one=...&lng_one=...&lat_two=...&lng_two=... — returns bunkry in a bounding box
• GET /api/search?prompt=<name> — returns one bunker by exact name
• GET /api/id?id=<opevneni_id(to)/ropiky_id(lo)>&type=<type "lo/to"> — returns the entire row from DB

Scripts and Utilities

• backend/dbupload.py
  • After having the db setup you can run this to load the database with bunkers:

    python -m backend.dbupload
    

    Note: The helper full_db_init.py script automatically populates the data, so if you ran that script dont run this one!

Development Notes

• Frontend depends on CDN links for Leaflet and Google Fonts in web/map/index.html.
• Authentication uses JWT stored in an HttpOnly cookie.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

• See the LICENSE file for the full text.
• If you contribute, you agree that your contributions will be licensed under GPL-3.0.