Getting Started

This guide walks you through setting up Codex and creating your first library.

System Requirements

• CPU: 1 core (2+ recommended for scanning)
• RAM: 512 MB (1 GB+ recommended)
• Storage: Depends on your library size and thumbnail cache
• OS: Linux, macOS, or Windows

Quick Start with Docker (Recommended)

The fastest way to get started is with a single docker run command:

docker run -d \
  --name codex \
  -p 8080:8080 \
  -v /path/to/your/library:/library:ro \
  -v codex-data:/app/data \
  -e PUID=1000 \
  -e PGID=1000 \
  -e CODEX_AUTH_JWT_SECRET="$(openssl rand -base64 32)" \
  ghcr.io/ashdevfr/codex:latest

Access Codex at http://localhost:8080. On first launch, you'll be guided through a setup wizard to create your admin account.

Finding Your User ID

Run id in your terminal to find your UID and GID. Use these values for PUID and PGID to avoid permission issues with mounted volumes.

Replace /path/to/your/library with the path to your comics, manga, or ebooks folder.

Volume Mounts

Container Path	Purpose
/app/data	Database (SQLite), thumbnails, and uploads
/library	Your media files (read-only recommended)

Library Permissions

Mount your media library as read-only (:ro) to prevent accidental modifications. Codex only needs read access to your files.

Docker Compose

For a more maintainable setup, see the Docker Deployment guide for Docker Compose examples.

First Login

1. Open Codex in your browser at http://localhost:8080
2. Complete the setup wizard to create your admin account

3. Optionally configure basic settings (application name, user registration)

4. Log in with your new credentials

Creating Your First Library

1. Click Libraries in the sidebar, then click + to add a new library
2. Fill in the General tab:
   • Name: A descriptive name (e.g., "My Comics")
   • Path: The folder path containing your files (use the container path, e.g., /library)
   • Default Reading Direction: Choose based on your content type

3. Configure the Strategy tab for how series and books are detected

4. Set up Scanning options:
   • Manual: Scan only when you trigger it
   • Automatic: Schedule regular scans with cron expressions

5. Click Create Library

Multiple Libraries (Docker)

Mount multiple folders in your Docker command or compose file:

volumes:
  - /media/comics:/library/comics:ro
  - /media/manga:/library/manga:ro
  - /media/ebooks:/library/ebooks:ro

Then create separate libraries pointing to /library/comics, /library/manga, etc.

Running Your First Scan

If you enabled "Scan on startup", Codex will automatically scan when the library is created.

For manual scans:

1. Go to your library in the sidebar
2. Click the Scan button
3. Choose Normal for incremental scan or Deep for full re-scan
4. Watch the progress in real-time

Browsing Your Library

Once scanning completes:

• Home: See "On Deck" (continue reading) and recently added series
• By Series: Click a library in the sidebar to browse series
• By Books: Toggle between series and books view

Reading a Book

1. Click on a book cover to open the reader
2. Navigate with arrow keys, swipe, or click left/right edges
3. Progress is saved automatically
4. Access settings via the gear icon in the toolbar

Upgrading

Docker

docker pull ghcr.io/ashdevfr/codex:latest
docker stop codex && docker rm codex
# Run your docker run command again

Troubleshooting

Library Not Found

Docker: Ensure the volume is mounted correctly:

docker exec codex ls -la /library

Books Not Appearing

1. Verify file format is supported (CBZ, CBR, EPUB, PDF)
2. Check files aren't corrupted
3. Run a deep scan to re-process all files

Login Issues

1. Verify credentials are correct
2. Check JWT secret is set in configuration
3. Clear browser cookies and try again

For more help, see the Troubleshooting Guide.

Next Steps

• Configuration options
• Docker Compose & PostgreSQL
• Running as a service
• OPDS for e-readers
• API documentation