actaria

actaria is an open-source scholarly journal publishing platform: diamond open access, first-class open peer review, LaTeX-only submissions, and multi-tenant from day one.

See docs/superpowers/specs/ for design specs and docs/superpowers/plans/ for implementation plans.

Quickstart

Everything runs under Docker Compose: Postgres, Redis, MinIO, Django web, and the RQ worker.

# First time, or after Dockerfile / dependency changes.
docker compose build

# Start postgres, redis, minio, web, and worker.
docker compose up -d

# Idempotent dev seed: migrations, license fixture, MinIO bucket, superuser,
# JOAS journal, sections, and manager role.
./scripts/init-joas-test.sh

# Build the Inertia/React bundle served by Django.
npm install
npm run build

Log in at http://localhost:8760/auth/login/:

• Email: root@actaria.local
• Password: actaria

Change the password before exposing the instance anywhere:

docker compose exec web uv run python manage.py changepassword root@actaria.local

If you are on a remote host over SSH, forward the port first:

ssh -L 8760:localhost:8760 <host>

Key URLs

After running ./scripts/init-joas-test.sh:

URL	Purpose
/	Platform landing page listing configured journals
/admin/	Django admin, superuser only
/auth/login/	Email/password login
/j/joas/	JOAS journal home
/j/joas/submit/	Author submission wizard
/j/joas/my-submissions/	Author submission list
/j/joas/office/	Editorial office dashboard
/j/joas/preprints/	Public preprint archive
/j/joas/preprint/<number>/	Public preprint detail
/j/joas/articles/	Public article index
/j/joas/article/<article-number>/	Public article detail
/healthz	Health check

The /j/<slug>/ prefix is configurable with ACTARIA_JOURNAL_PATH_PREFIX.

Common Development Commands

# Logs and service state.
docker compose logs -f web
docker compose ps

# Stop services. Data persists under ./data/.
docker compose down

# Stop services and remove the /opt/venv named volume.
docker compose down -v

# Rebuild the frontend bundle after editing resources/js or resources/css.
npm run build

# Vite dev server with HMR at http://localhost:5173/.
npm run dev

# TypeScript check.
npm run typecheck

Manual wizard test zip:

uv run scripts/build-example-zip.py

This writes example.zip containing main.tex, references, and a figure.

Testing

# Python unit/integration tests.
uv run pytest

# Browser UI tests.
uv run pytest tests/playwright/

# Docker integration tests, including real TeX Live compile cases.
uv run pytest -m docker

Playwright requires Chromium in the runtime where tests run:

uv run playwright install chromium

When services are already running, container execution is closest to the web runtime:

docker compose exec web uv run pytest
docker compose exec web uv run pytest tests/playwright/

Configuration

• .env is gitignored. Copy .env.example on first setup if you need local overrides.
• Key variables: SECRET_KEY, DATABASE_URL, REDIS_URL, S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, ORCID_CLIENT_ID, ORCID_CLIENT_SECRET, ACTARIA_JOURNAL_PATH_PREFIX, ACTARIA_BASE_URL, CSRF_TRUSTED_ORIGINS, and ACTARIA_DATA_DIR.
• docker-compose.yml overrides database, Redis, and S3 endpoints inside the Compose network.

Ports

Service	Container port	Host port	Notes
web	8760	8760	Django
postgres	5432	6432	Avoids host Postgres collisions
redis	6379	6379	Queue/cache
minio	9000 / 9001	9000 / 9001	API / console (minioadmin)

Data Persistence

Stateful services bind-mount under ./data/ by default:

./data/postgres
./data/redis
./data/minio

Set ACTARIA_DATA_DIR to keep data elsewhere. To wipe local dev data:

docker compose down
rm -rf data/

Compile Worker

The worker uses Docker-out-of-Docker: actaria-worker mounts the host Docker socket and starts sibling TeX Live containers for compile jobs. The scratch directory must exist on the host and be writable by UID 1000:

mkdir -p /tmp/actaria-compile

Important compile knobs:

Env var	Default	Notes
ACTARIA_TEXLIVE_IMAGE	texlive/texlive:latest	TeX Live image
ACTARIA_COMPILE_MEMORY	2g	Per-compile memory cap
ACTARIA_COMPILE_CPUS	1	Per-compile CPU cap
ACTARIA_COMPILE_TIMEOUT	60	latexmk wall-clock timeout in seconds
ACTARIA_COMPILE_TMPFS_SIZE	512m	/tmp inside sandbox
ACTARIA_COMPILE_USER	1000:1000	UID/GID inside sandbox

Sandbox invariants are pinned by tests/test_sandbox_invariants.py: no network, read-only root filesystem, resource limits, non-root user, and latexmk -no-shell-escape.

Known Limits

• Manuscript zip: <= 20 MB compressed, <= 200 MB uncompressed, <= 500 entries.
• Supplementary files: 20 MB each, 100 MB total per submission.
• Output PDF: <= 100 MB.
• PDFs and source artifacts are served through Django proxy views, not public presigned object-storage URLs.

Development Notes

• Python dependencies are managed by uv.
• Frontend source lives under resources/js/; Django serves the built bundle from static/dist/.
• Always run npm run build after editing frontend source before relying on browser behavior through Django.
• Pre-commit hooks run ruff, formatting, large-file checks, and the journal isolation-test gate. Enable them with uv run pre-commit install.