knowledgecenter

Installation & Setup

to test as docker

docker run -p 9922:9922 -v /path/to/content:/content -e ATLAS_CONTENT_PATH=/content atlasserver:latest

to run natively

export ATLAS_CONTENT_PATH="${HOME}/code/forge.ourworld.tf/forge.ourworld.tf/ourworld/atlas_ourworld"
${HOME}/code/forge.ourworld.tf/lhumina_research/atlasserver/start_server_debug.sh

First Time Setup

./install.sh

This will:

• Install uv if not present
• Create a Python virtual environment
• Install all dependencies from pyproject.toml
• Use local herolib if available at ~/code/forge.ourworld.tf/lhumina_research/herolib_python

Force Update herolib

If you need to update to the latest herolib from git (e.g., after upstream changes):

./install.sh --force

This forces a clean reinstall of herolib from the git repository, bypassing the cache.

Starting the Server

Production mode:

./start_server.sh

Server runs on port 9922 at http://localhost:9922

Development mode:

./start_server_debug.sh

Runs with debug mode enabled and auto-reload on code changes.

ngrok

to be able to test on own environment

ngrok login
ngrok http 9022

it lets me expose a local development server to the internet, which is useful for testing webhooks and other integrations.

example url https://e68c72dd903a.ngrok-free.app = ngrok url

then go e.g. to https://e68c72dd903a.ngrok-free.app/info/welcome

now we can test the registration flow

now put your ngrok URL in cfg/dev.toml

to start in development mode do start_server_debug.sh

Rsync Site Deployment (CI/CD)

Atlas Server includes a built-in rsync daemon that allows Forgejo CI pipelines to push built static sites directly into the running container. No restart required — Flask picks up the new files immediately.

How it works

Forgejo CI (website repo)
    │
    │  git push triggers CI build
    │
    ▼
CI runner builds static site
    │
    │  rsync -avz --port=8873 ...
    │    ./dist/ atlas@server::sites/
    │
    ▼
Atlas Server container (port 8873)
    │
    │  rsync daemon writes to ~/hero/www/info/
    │
    ▼
Flask app (port 9922)
    │
    │  [[sites]] path = "${HOME}/hero/www/info"
    │
    ▼
Users browse the site

Server-side configuration

Enable rsync in your content repo's TOML config (e.g. cfg/prod.toml):

[rsync]
enabled = true
secret = "your-secret-password"
port = 8873
sites_dir = "${HOME}/hero/www/info"

The rsync secret is stored in the TOML config file. At container startup, start_rsync.py reads this config and starts an rsync daemon on port 8873 with the configured credentials.

When running the container, expose the rsync port alongside the web port:

docker run -p 9922:9922 -p 8873:8873 \
  -e ATLAS_CONTENT_GITURL=git@forge.ourworld.tf:ourworld/atlas_ourworld.git \
  -e ATLAS_GIT_DEPLOY_KEY="${ATLAS_GIT_DEPLOY_KEY}" \
  atlasserver:latest

CI-side: pushing sites

In your Forgejo CI pipeline, after building the site:

echo "your-secret-password" > /tmp/rsync-password
chmod 600 /tmp/rsync-password

rsync -avz --port=8873 --delete \
  --password-file=/tmp/rsync-password \
  /path/to/built/sites/ \
  atlas@your-server.com::sites/

rm /tmp/rsync-password

• atlas@ — the rsync user (hardcoded in the daemon config)
• ::sites/ — the rsync module name
• --delete — removes files on the server that no longer exist in the build output

Registering sites in the config

Synced sites land in sites_dir. Reference them in the TOML config so Flask serves them:

[[sites]]
path = "${HOME}/hero/www/info/mysite"
name = "mysite"

[[sites]]
path = "${HOME}/hero/www/info/docs"
name = "docs"

python tips

import pudb; pudb.set_trace()