Docforge

Engineering the live experience.

Docforge is a FastAPI + Docker service that turns Twisted Melon project metadata, license certificates, and other artifacts into PDF documents.

---

Prerequisites

• Docker Desktop running
• Git installed
• A GitHub personal access token (only required if you use the GitHub-backed routes — most local users can leave it blank)

---

Clean install

Run this on a fresh Docker host to install Docforge from scratch:

# 1. Clone the repo
git clone https://github.com/TwistedMelonIO/docforge.git
cd docforge

# 2. Set up the environment file
cp .env.example .env
# (optional) open .env and paste your GitHub PAT into GITHUB_TOKEN=

# 3. Build and start the container
docker compose up -d --build

Once it's up, Docforge is reachable at http://localhost:8899.

Note: docker-compose.yml mounts a host path into /projects for project-metadata access. On a machine that isn't the original dev box, edit line 12 of docker-compose.yml and point it at your own projects directory (or remove the mount if you don't need that integration).

---

Update an existing install

Run this in the existing docforge/ directory to pull the latest release and rebuild:

# 1. Pull the latest code
git fetch --tags
git checkout main
git pull origin main

# 2. Rebuild the container against the new code
docker compose down
docker compose up -d --build

To pin to a specific release tag instead of main:

git fetch --tags
git checkout v1.1.1     # or whichever release
docker compose down
docker compose up -d --build

Verify the running version:

curl http://localhost:8899/ | grep version

---

Stop / start / remove

docker compose stop                # stop the container
docker compose start               # start it again
docker compose down                # stop and remove the container (keeps volumes)
docker compose down -v             # also remove volumes (destructive)

---

Troubleshooting

• Port 8899 already in use — find the process with lsof -iTCP:8899 -sTCP:LISTEN and stop it, or change the host-side port in docker-compose.yml (line 8).
• Mount errors on /projects — fix or remove the host-path mount on line 12 of docker-compose.yml. Docker Desktop's File Sharing settings must include the parent of that path.
• Container starts but API is empty — check logs: docker logs docforge --tail 100.

---

Built by Twisted Melon — engineering the live experience.