From b67eb6fec0022321892c54769e29988caa665804 Mon Sep 17 00:00:00 2001
From: FuzzyGrim <stromed_chariotman@aleeas.com>
Date: Fri, 15 May 2026 12:40:11 +0200
Subject: [PATCH] add local development docs page

---
 docs/local-development.md | 93 +++++++++++++++++++++++++++++++++++++++
 docs/setup.md             | 46 +------------------
 mkdocs.yml                |  1 +
 3 files changed, 95 insertions(+), 45 deletions(-)
 create mode 100644 docs/local-development.md

diff --git a/docs/local-development.md b/docs/local-development.md
new file mode 100644
index 00000000..891c1f60
--- /dev/null
+++ b/docs/local-development.md
@@ -0,0 +1,93 @@
+# Local Development
+
+This page covers working on Yamtrack from source.
+
+## Prerequisites
+
+- Python 3.12
+- Docker
+- Redis
+
+## 1. Clone the repository
+
+```bash
+git clone https://github.com/FuzzyGrim/Yamtrack.git
+cd Yamtrack
+```
+
+## 2. Start Redis
+
+If you do not already have Redis running locally, start it with Docker:
+
+```bash
+docker run -d --name redis -p 6379:6379 --restart unless-stopped redis:8-alpine
+```
+
+## 3. Create a virtual environment
+
+```bash
+python -m venv venv
+venv/bin/python -m pip install -U -r requirements-dev.txt
+venv/bin/pre-commit install
+```
+
+## 4. Configure environment values
+
+Create a `.env` file in the repository root:
+
+```bash
+TMDB_API=API_KEY
+MAL_API=API_KEY
+IGDB_ID=IGDB_ID
+IGDB_SECRET=IGDB_SECRET
+STEAM_API_KEY=STEAM_API_SECRET
+BGG_API_TOKEN=BGG_API_TOKEN
+SECRET=SECRET
+DEBUG=True
+```
+
+See [Environment Variables](env-variables.md) for the full list of supported settings.
+
+## 5. Prepare the database
+
+```bash
+cd src
+../venv/bin/python manage.py migrate
+```
+
+## 6. Run the app
+
+Run the Django development server:
+
+```bash
+cd src
+../venv/bin/python manage.py runserver
+```
+
+Run the Celery worker with the scheduler in another terminal:
+
+```bash
+cd src
+../venv/bin/celery -A config worker --beat --scheduler django --loglevel DEBUG
+```
+
+Run Tailwind in another terminal:
+
+```bash
+cd src
+../venv/bin/tailwindcss -i ./static/css/input.css -o ./static/css/tailwind.css --watch
+```
+
+Open the development server at:
+
+```text
+http://localhost:8000
+```
+
+## Documentation
+
+Install the docs dependencies with the development requirements, then serve the current checkout:
+
+```bash
+venv/bin/mkdocs serve --livereload
+```
diff --git a/docs/setup.md b/docs/setup.md
index 41e76e3d..e011022b 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -1,6 +1,6 @@
 # Setup
 
-This page covers running Yamtrack with Docker and setting up a local development environment.
+This page covers running Yamtrack with Docker.
 
 ## Docker
 
@@ -85,50 +85,6 @@ services:
 
 If you see `403 Forbidden` behind a proxy, check that `URLS` exactly matches the public URL you use in the browser.
 
-## Local Development
-
-For development, clone the repository and change directory to it:
-
-```bash
-git clone https://github.com/FuzzyGrim/Yamtrack.git
-cd Yamtrack
-```
-
-Install Redis or start a Redis container:
-
-```bash
-docker run -d --name redis -p 6379:6379 --restart unless-stopped redis:8-alpine
-```
-
-Create a `.env` file in the repository root:
-
-```bash
-TMDB_API=API_KEY
-MAL_API=API_KEY
-IGDB_ID=IGDB_ID
-IGDB_SECRET=IGDB_SECRET
-STEAM_API_KEY=STEAM_API_SECRET
-BGG_API_TOKEN=BGG_API_TOKEN
-SECRET=SECRET
-DEBUG=True
-```
-
-Then install dependencies and run the app:
-
-```bash
-python -m pip install -U -r requirements-dev.txt
-pre-commit install
-cd src
-python manage.py migrate
-python manage.py runserver & celery -A config worker --beat --scheduler django --loglevel DEBUG & tailwindcss -i ./static/css/input.css -o ./static/css/tailwind.css --watch
-```
-
-Open the development server at:
-
-```text
-http://localhost:8000
-```
-
 ## Troubleshooting
 
 Check the Yamtrack container logs:
diff --git a/mkdocs.yml b/mkdocs.yml
index 4d4b41a9..62de215a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,6 +11,7 @@ edit_uri: edit/dev/docs/
 nav:
   - Home: index.md
   - Setup: setup.md
+  - Local Development: local-development.md
   - Environment Variables: env-variables.md
   - Media Imports: media-imports.md
   - Social Auth: social-auth.md