radegastedr/console repository overview

⁠Radegast EDR -- Backend

Radegast EDR is a lightweight, privacy-focused Endpoint Detection and Response platform perfect for smaller teams, home labbers, and families. With complete end-to-end encryption (E2EE) using age encryption, your log data remains private and secure -- even from the server itself.

⁠Quickstarts

• User Quickstart: First Steps with Radegast EDR⁠
• Backend Quickstart: Deployment & Quick Start⁠

Built with FastAPI and SQLAlchemy, the backend handles device authorization, user configuration packs, encrypted log storage, alert status tracking, and key/session management.

⁠Deployment (Podman / Docker)

The recommended way to run Radegast EDR in production is via the published container image.

⁠Quick start

# Pull and start with podman-compose (reads podman-compose.yaml)
podman-compose up -d

# Or with plain podman / docker
podman run -d \
  --name radegast-edr \
  -p 8000:8000 \
  -e RADEGAST_SECRET_KEY=<your-secret> \
  -e RADEGAST_BASE_URL=https://your.domain \
  -e RADEGAST_CORS_ORIGINS=https://your.domain \
  -v radegast_db:/app/data/db \
  -v radegast_uploads:/app/data/uploads \
  -v radegast_releases:/app/data/releases \
  docker.io/radegastedr/console:latest

⁠Using podman-compose

Clone the repository and start all services with persistent named volumes:

git clone https://github.com/radegast-edr/radegast-backend.git
cd radegast-backend

# Edit the environment section in podman-compose.yaml first, then:
podman-compose up -d

Three named volumes are created automatically:

The API is available at http://localhost:8000⁠ and the interactive docs at http://localhost:8000/docs⁠.

⁠Using MySQL as Database

By default, the application runs on SQLite. If you want to use MySQL or MariaDB:

1. Ensure your MySQL database is created.
2. Run the Docker container with RADEGAST_DATABASE_URL pointed to your database using the mysql+aiomysql:// driver (the Docker image comes pre-installed with mysql extra/support):

   docker run -d \
     --name radegast-edr \
     -p 8000:8000 \
     -e RADEGAST_SECRET_KEY=<your-secret> \
     -e RADEGAST_DATABASE_URL="mysql+aiomysql://user:password@mysql-host:3306/db_name" \
     -e RADEGAST_BASE_URL=https://your.domain \
     -e RADEGAST_CORS_ORIGINS=https://your.domain \
     -v radegast_uploads:/app/data/uploads \
     -v radegast_releases:/app/data/releases \
     docker.io/radegastedr/console:latest
   

   Copy

SSL/TLS parameters such as ?ssl_verify_cert=false (for self-signed certs), ?ssl_ca=/path/to/ca.pem, ?ssl_cert=..., or ?ssl_mode=... in the URL query string are automatically parsed into the appropriate TLS context for aiomysql.

To copy an existing SQLite database (e.g. radegast.db) to MySQL, use the migration utility script:

# Run migration (applies Alembic migrations to MySQL and copies all data)
uv run python migrate-to-mysql.py \
  --sqlite-path radegast.db \
  --mysql-url "mysql+aiomysql://user:password@mysql-host:3306/db_name?ssl_ca=cert.pem"

The script automatically runs Alembic migrations on MySQL, disables foreign key checks to handle circular dependencies, normalizes datetime formats, batches transactions to stay within MySQL's binlog limits, preserves auto-increment counters, and verifies matching row counts across all tables.

⁠Local Development

⁠Prerequisites

• Python 3.11+
• uv⁠ (recommended) or standard pip

⁠Installation

1. Install project dependencies:

   uv sync
   # Or to install with MySQL support:
   # uv sync --group mysql
   
   # Or using standard pip with a virtual environment:
   # python -m venv .venv && source .venv/bin/activate && pip install .
   # Or with MySQL support:
   # pip install .[mysql]
   

   Copy

2. Install dev tools (test runner etc.):

   uv sync --dev
   # Or:
   # pip install .[dev]
   

   Copy

⁠Running the Backend

Start the development server with hot-reload:

uv run uvicorn app.main:app --reload --port 8000

The server runs on http://localhost:8000⁠. Interactive Swagger docs are available at http://localhost:8000/docs⁠.

⁠Running with the CLI

You can run the application directly via the CLI interface. In development, use:

uv run radegast-console run --host=127.0.0.1 --port=8000 --workers=4

Alternatively, you can install the tool globally using uv:

uv tool install radegast-edr-console

Once installed, start the console using:

radegast-console run --host=127.0.0.1 --port=8000 --workers=4

You can pass any configuration variable (e.g., --database-url, --enable-email-worker) to override defaults. Run radegast-console run --help to see a full list of options.

⁠Running Tests

uv run pytest

⁠Configuration

All settings are controlled via environment variables prefixed with RADEGAST_ (defined in app/config.py⁠):