mirror/mantrae
1
0
Fork 0
mirror of https://github.com/MizuchiLabs/mantrae.git synced 2025-12-16 20:05:17 -06:00
Code Issues Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
d34dscene
2025-08-01 00:47:18 +02:00
parent 29f20b02a7
commit d89e140a6d
29 changed files with 12000 additions and 16680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
agent/cmd/main.go
View File

@@ -16,9 +16,7 @@ import (
)
func main() {
// update := flag.Bool("update", false, "Update to latest version")
version := flag.Bool("version", false, "Show version")
flag.Parse()
if *version {
@@ -26,21 +24,6 @@ func main() {
return
}
// quit := make(chan os.Signal, 1)
// signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
// logger.Setup()
// ctx, cancel := context.WithCancel(context.Background())
// defer cancel()
// // start agent loop
// go client.Client(ctx)
// <-quit
// slog.Info("Shutting down agent...")
// cancel()
// <-ctx.Done()
logger.Setup()
cfg, err := client.Load()
@@ -63,6 +46,7 @@ func main() {
agent := client.NewAgent(cfg)
// Handle graceful shutdown
go func() {
<-quit
slog.Info("Shutting down agent...")

1
agent/internal/client/client.go
View File

@@ -38,6 +38,7 @@ func NewAgent(cfg *Config) *Agent {
}
func (a *Agent) Run(ctx context.Context) {
// Run initial health check
a.healthCheck(ctx)
healthTicker := time.NewTicker(a.config.HealthCheckInterval)

22
docs/docs/01-intro.md
View File

@@ -1,22 +0,0 @@
---
sidebar_position: 1
---
# Welcome to Mantrae
**Mantrae** is a modern frontend interface for managing [Traefik](https://traefik.io/) configurations, built using **Go** for backend services and **Svelte** for a reactive frontend experience. With Mantrae, you can easily create, update, and manage routers, middlewares, and other Traefik components.
## Key Features
- **Manage Routers:** Effortlessly create and configure routers for various services.
- **Configure Middlewares:** Apply middlewares for advanced routing capabilities, including rate limiting, authentication, and more.
- **Real-Time Updates:** Get instant feedback and updates with a Svelte-powered UI.
- **Built with Go:** Leverage the reliability and performance of Go for backend operations.
## Getting Started
To install and set up Mantrae, refer to our [Installation Guide](./installation).
---
Let’s get started with Mantrae and simplify your Traefik management!

65
docs/docs/02-installation.md
View File

@@ -1,65 +0,0 @@
---
sidebar_position: 2
---
# Installation
Follow these instructions to install and start using Mantrae with Traefik.
## Prerequisites
1. **Install Traefik**: Ensure you have a running instance of
[Traefik](https://traefik.io/).
2. **Generate a Secret**: Create a secure, random secret key to use with
Mantrae:
```bash
openssl rand -hex 32
```
Copy the generated secret as you’ll need it in the next steps.
## Installation Options
### Option 1: Download the Binary
1. Visit the [releases page](https://github.com/mizuchilabs/mantrae/releases) to
download the latest Mantrae binary for your platform.
2. Run the binary with:
```bash
export SECRET=<your_secret>
./mantrae
```
### Option 2: Use Docker
Run Mantrae in a Docker container:
```bash
docker run --name mantrae -e SECRET=<your_secret> -d -p 3000:3000 ghcr.io/mizuchilabs/mantrae:latest
```
### Option 3: Docker Compose (Mantrae + Traefik)
Use the provided `docker-compose.yml` file to deploy Mantrae and Traefik
together.
1. Download the example
[docker-compose.yml](https://github.com/mizuchilabs/mantrae/blob/main/docker-compose.yml).
2. Run the following command to start both services:
```bash
docker-compose up -d
```
## Access the Web UI
Once Mantrae is running, open your browser and navigate to:
[http://localhost:3000](http://localhost:3000)
Log in using the user `admin` and the generated password, which will display on
the first run.
## CLI Options
- `-version`: Print the version.
- `-update`: Update mantrae to the latest version. (Will not work inside docker
container!)

20
docs/docs/03-faq.md
View File

@@ -1,20 +0,0 @@
---
sidebar_position: 4
---
# FAQ
### Why would I use this? Traefik already has configuration discovery.
Yes, Traefik has amazing configuration discovery capabilities for various providers (Docker, Kubernetes, etc.). But for all those times you can't use these features (e.g. multiple machines not connected via Docker Swarm or Kubernetes) you have to use the file provider. Mantrae helps you with that and adds additional automation features like managing DNS records as well, similar to external-dns for Kubernetes.
### I want to use multiple DNS providers of the same type (e.g. multiple cloudflare accounts), how do I do that?
Traefik doesn't support multiple DNS Challenge providers, so you have to use CNAME records to manage multiple accounts.
E.g. if you have a domain `example.com` on account "Foo" and a domain `example.org` on account "Bar", you can add the API Key for account "Foo" normally, but to get letsencrypt certificates for `example.org` you need add a CNAME record for `example.org` with these values:
- Type: `CNAME`
- Name: `_acme-challenge.example.org`
- Target: `_acme-challenge.example.com`
Now you can request certificates for `sub.example.org` as well.

50
docs/docs/api.md Normal file
View File

@@ -0,0 +1,50 @@
---
sidebar_position: 9
---
# API Reference
Mantrae exposes a comprehensive API for programmatic access to all configuration management features. The API is built using gRPC with the Connect protocol, providing both gRPC and HTTP/JSON interfaces.
## API Endpoints
The Mantrae API documentation is available at:
```
http://localhost:3000/docs
```
Each service has its own endpoint under this base path.
## Authentication
All API requests require authentication. You can authenticate using:
1. **Session cookies**: Automatically set when logging in through the web interface
2. **Authorization header**: Bearer token for programmatic access
For programmatic access, obtain an API token through the web interface or create one using the UserService API.
## Dynamic Configuration API
In addition to the management API, Mantrae provides endpoints for Traefik to consume dynamic configuration:
### Profile Configuration Endpoint
```
GET /api/{profile-name}
```
Query Parameters:
- `token`: Profile token for authentication
- `format`: Response format (json or yaml)
Headers:
- `Accept`: Alternative way to specify format (application/json or application/x-yaml)
This endpoint returns the complete Traefik dynamic configuration for the specified profile.
Example:
```bash
curl "http://localhost:3000/api/production?token=PROFILE_TOKEN&format=yaml"
```

114
docs/docs/faq.md Normal file
View File

@@ -0,0 +1,114 @@
---
sidebar_position: 4
---
# FAQ
## General Questions
### Why would I use this? Traefik already has configuration discovery.
Yes, Traefik has amazing configuration discovery capabilities for various providers (Docker, Kubernetes, etc.). But for all those times you can't use these features (e.g. multiple machines not connected via Docker Swarm or Kubernetes) you have to use the file provider. Mantrae helps you with that and adds additional automation features like managing DNS records as well, similar to external-dns for Kubernetes.
Mantrae is particularly useful when you need to:
- Manage multiple separate Traefik instances from a single interface
- Automatically synchronize configurations from remote Docker hosts using agents
- Have a visual interface for managing complex routing configurations
- Centralize DNS management across multiple domains and providers
### What's the difference between using Mantrae and Traefik's file provider directly?
Using Mantrae provides several advantages over direct file provider management:
- Web-based interface for easier configuration management
- Multi-profile support for different environments
- Agent-based automatic discovery of container configurations
- Built-in DNS provider integration for certificate management
- Backup and restore capabilities
- User management and audit logging
- Real-time configuration updates without manual file editing
## DNS Providers
### I want to use multiple DNS providers of the same type (e.g. multiple Cloudflare accounts), how do I do that?
Traefik doesn't support multiple DNS Challenge providers, so you have to use CNAME records to manage multiple accounts.
E.g. if you have a domain `example.com` on account "Foo" and a domain `example.org` on account "Bar", you can add the API Key for account "Foo" normally, but to get letsencrypt certificates for `example.org` you need add a CNAME record for `example.org` with these values:
- Type: `CNAME`
- Name: `_acme-challenge.example.org`
- Target: `_acme-challenge.example.com`
Now you can request certificates for `sub.example.org` as well.
### Can I use different DNS providers for different domains within the same profile?
Yes, you can configure multiple DNS providers within a single profile and assign different providers to different routers. This allows you to manage domains across multiple DNS providers from a single Mantrae profile.
## Agents
### How do agents handle network connectivity when behind firewalls?
Agents establish outbound connections to the Mantrae server, so they work well in environments where the Mantrae server is in a DMZ or cloud environment, and agents are behind firewalls. The Mantrae server does not need to initiate connections to the agents.
### What happens if an agent loses connectivity to the Mantrae server?
When an agent loses connectivity:
1. The agent will continue to monitor Docker containers locally
2. Upon reconnection, the agent will synchronize any changes that occurred while offline
3. The Mantrae server will mark the agent as offline after a timeout period
4. Existing configurations will continue to function in Traefik
### Can I run multiple agents on the same host?
Yes, you can run multiple agents on the same host, each configured for different profiles or with different tokens. This is useful in environments where you need to separate configurations for different purposes.
## Profiles & Multi-Environment Management
### Can I share configurations between profiles?
Currently, configurations are profile-specific for security and isolation. However, you can export configurations from one profile and import them into another through the backup/import functionality.
### How do I migrate from a single-profile setup to multi-profile?
1. Create new profiles for each environment
2. Export your existing configuration
3. Import the configuration into each new profile as needed
4. Update your Traefik instances to point to the new profile endpoints
## Security
### How are credentials and secrets protected?
- Passwords are hashed using bcrypt with a cost factor of 12
- API tokens are generated using cryptographically secure random generators
- Database connections use prepared statements to prevent SQL injection
- Communication between agents and the server can be secured with HTTPS
- DNS provider credentials are encrypted at rest in the database
### Can I enforce specific security policies?
Mantrae supports:
- OIDC/SAML integration for enterprise authentication
- Audit logging of all configuration changes
- Regular backup capabilities for disaster recovery
## Troubleshooting
### My routers aren't working, how can I debug this?
1. Check the Traefik logs for any error messages related to configuration loading
2. Verify that the profile token in your Traefik configuration is correct
3. Ensure the Mantrae server is accessible from your Traefik instance
4. Check that the router rules are syntactically correct
5. Confirm that services referenced by routers exist and are correctly configured
## Development & Customization
### Is there an API I can integrate with?
Yes, Mantrae exposes a gRPC API using the Connect protocol. The API definitions are in the `proto/mantrae/v1/` directory of the source code.
### How do I request new features?
Feature requests can be submitted as GitHub issues in the Mantrae repository. Community contributions are also welcome through pull requests.

37
docs/docs/index.md Normal file
View File

@@ -0,0 +1,37 @@
---
title: Mantrae Documentation
---
# Mantrae Documentation
Welcome to the official documentation for Mantrae, a modern web interface for managing Traefik configurations.
## Getting Started
If you're new to Mantrae, start with these essential guides:
- [Introduction](intro) - Learn what Mantrae is and its key features
- [Installation](installation) - Install Mantrae using Docker, binary, or from source
- [Profiles](usage/profiles) - Understand how to manage multiple Traefik environments
- [Agents](usage/agents) - Set up agents for automatic configuration discovery
## Core Concepts
- **Profiles**: Logical separation of configurations for different environments
- **Agents**: Remote collectors that automatically discover container configurations
- **DNS Providers**: Integration with Cloudflare, PowerDNS, and Technitium for certificate management
- **Dynamic Configuration**: Real-time configuration generation for Traefik instances
## Advanced Topics
- [Environment Configuration](usage/environment) - Configure Mantrae with environment variables
- [Backups & Restoration](usage/backups) - Protect your configurations with automated backups
- [API Reference](api) - Programmatically manage your Traefik configurations
## Need Help?
- Check the [FAQ](faq) for common questions and troubleshooting tips
- Report issues on [GitHub](https://github.com/mizuchilabs/mantrae/issues)
- Join our community discussions
Mantrae simplifies Traefik management by providing a user-friendly interface for complex routing configurations, making it easier than ever to manage your reverse proxy setup.

61
docs/docs/installation.md Normal file
View File

@@ -0,0 +1,61 @@
---
sidebar_position: 2
---
# Installation
Follow these instructions to install and start using Mantrae with Traefik.
## Prerequisites
1. **Install Traefik**: Ensure you have a running instance of [Traefik](https://traefik.io/).
2. **Generate a Secret**: Create a secure, random secret key to use with Mantrae:
```bash
openssl rand -hex 32
```
Copy the generated secret as you'll need it in the next steps.
## Installation Options
### Option 1: Download the Binary
1. Visit the [releases page](https://github.com/mizuchilabs/mantrae/releases) to download the latest Mantrae binary for your platform.
2. Run the binary with:
```bash
export SECRET=<your_secret>
export ADMIN_PASSWORD=<your_admin_password>
./mantrae
```
### Option 2: Use Docker
Run Mantrae in a Docker container:
```bash
docker run --name mantrae -e SECRET=your_secret -e ADMIN_PASSWORD=your_admin_password -p 3000:3000 -v mantrae-data:/app/data ghcr.io/mizuchilabs/mantrae:latest
```
### Option 3: Docker Compose (Mantrae + Traefik)
Use the provided `docker-compose.yml` file to deploy Mantrae and Traefik together.
1. Checkou out the example [docker-compose.yml](https://github.com/mizuchilabs/mantrae/blob/main/docker-compose.yml) and modify it to suit your needs.
2. Run the following command to start the services:
```bash
docker compose up -d
```
## Access the Web UI
Once Mantrae is running, open your browser and navigate to:
[http://localhost:3000](http://localhost:3000)
Log in using the default credentials:
- Username: `admin`
- Password: `your_admin_password`
## CLI Options
- `-version`: Print the version.
- `-update`: Update Mantrae to the latest version. (Will not work inside docker container!)

30
docs/docs/intro.md Normal file
View File

@@ -0,0 +1,30 @@
---
sidebar_position: 1
---
# Welcome to Mantrae
**Mantrae** is a modern web interface for managing [Traefik](https://traefik.io/) configurations, built using **Go** for backend services and **SvelteKit** for a reactive frontend experience. With Mantrae, you can easily create, update, and manage routers, middlewares, services, and other Traefik components across multiple profiles.
To understand how Mantrae works, check out our [Architecture](./architecture) documentation.
## Key Features
- **Multi-Profile Management**: Create and manage multiple profiles to handle different Traefik instances (development, staging, production)
- **Agent-Based Configuration**: Deploy agents to remote machines to automatically collect Docker container information and Traefik labels
- **Unified Configuration Interface**: Manage HTTP, TCP, and UDP routers, services, and middlewares from a single dashboard
- **Dynamic Config Generation**: Generate Traefik dynamic configuration files in real-time
- **DNS Integration**: Built-in support for Cloudflare, PowerDNS, and Technitium DNS providers
- **Backup & Restore**: Automatic backup of configurations with restore capabilities
- **Real-Time Updates**: Get instant feedback with a SvelteKit-powered reactive UI
## How It Works
1. **Create Profiles**: Set up profiles for different environments (dev, staging, production)
2. **Deploy Agents** (Optional): Install agents on remote machines to automatically collect container information
3. **Configure Traefik**: Point your Traefik instances to Mantrae's dynamic configuration endpoints
4. **Manage Configuration**: Use the web UI to create and manage your routing configuration
## Getting Started
To install and set up Mantrae, refer to our [Installation Guide](./installation).

165
docs/docs/quickstart.md Normal file
View File

@@ -0,0 +1,165 @@
---
sidebar_position: 2
---
# Quick Start
Get Mantrae up and running quickly with this guide. This will walk you through installing Mantrae, creating your first profile, and configuring Traefik to use it.
## Prerequisites
- Docker (recommended) or ability to run Go binaries
- A running Traefik instance
- OpenSSL or similar tool to generate a secret
## Step 1: Generate a Secret
First, generate a secure secret for Mantrae:
```bash
openssl rand -hex 32
```
Save this secret for the next step.
## Step 2: Run Mantrae
### Using Docker (Recommended)
```bash
docker run --name mantrae \
-e SECRET=your-generated-secret \
-e ADMIN_PASSWORD=your-admin-password \
-p 3000:3000 \
-v mantrae-data:/app/data \
ghcr.io/mizuchilabs/mantrae:latest
```
### Using Docker Compose
Create a `docker-compose.yml` file:
```yaml
services:
mantrae:
image: ghcr.io/mizuchilabs/mantrae:latest
container_name: mantrae
environment:
- SECRET=your-generated-secret
- ADMIN_PASSWORD=your-admin-password
ports:
- "3000:3000"
volumes:
- mantrae-data:/app/data
restart: unless-stopped
volumes:
mantrae-data:
```
Then run:
```bash
docker compose up -d
```
## Step 3: Access the Web Interface
Open your browser and navigate to:
[http://localhost:3000](http://localhost:3000)
Log in with the username `admin` and your admin password.
- Username: `admin`
- Password: `your-admin-password`
**Important**: Change the default password immediately after first login!
## Step 4: Use the default profile or create your own
1. Click on the profile dropdown in the top navigation
2. Select "Create New Profile"
3. Enter profile details:
- Name: `another-profile`
- Description: `New profile for another site`
4. Click "Create"
## Step 5: Configure Traefik
Update your Traefik configuration to use Mantrae as a dynamic configuration provider.
### Using Traefik Configuration File
```yaml
providers:
http:
endpoint: "http://mantrae:3000/api/default?token=PROFILE_TOKEN"
pollInterval: "5s"
```
### Using Docker Compose
```yaml
services:
traefik:
image: traefik:latest
container_name: traefik
command:
- --providers.http.endpoint=http://mantrae:3000/api/default?token=PROFILE_TOKEN
- --providers.http.pollInterval=5s
- --entrypoints.web.address=:80
- --entrypoints.websecure.address=:443
ports:
- "80:80"
- "443:443"
restart: unless-stopped
```
**Note**: Replace `PROFILE_TOKEN` with the actual token from your profile (visible in the profile settings).
## Step 6: Create Your First Router
1. In the Mantrae web interface, navigate to "Routers"
2. Click "Add Router"
3. Configure your router:
- Name: `whoami`
- Rule: `Host(\`whoami.local\`)`
- Service: Create a new service pointing to your backend
- Optional: Add middlewares or entry points
4. Save the router
## Step 7: Test Your Configuration
If you've set up everything correctly, Traefik should now be routing requests based on your Mantrae configuration.
You can verify the dynamic configuration by accessing:
```
http://localhost:3000/api/default?token=PROFILE_TOKEN
```
This should return the JSON configuration that Traefik is using.
## Next Steps
- [Learn about Profiles](./usage/profiles) to manage multiple environments
- [Set up Agents](./usage/agents) for automatic container discovery
- [Configure DNS Providers](./usage/dns) for automatic certificate management
- [Explore Backups](./usage/backups) to protect your configurations
## Troubleshooting
### "Invalid token" errors
Ensure that the token in your Traefik configuration matches the profile token in Mantrae.
### Traefik not picking up changes
- Check that Traefik can reach the Mantrae server
- Verify the poll interval is reasonable (5-30 seconds)
- Check Traefik logs for any error messages
### Can't access the web interface
- Ensure the port mapping is correct in your Docker configuration
- Check that no other service is using port 3000
- Verify the container is running with `docker ps`

47
docs/docs/usage/01-profiles.md
View File

@@ -1,47 +0,0 @@
---
sidebar_position: 1
---
# Profiles
Mantrae allows you to create and manage multiple profiles, making it easy to configure multiple different Traefik instances. Profiles can be created and selected from the dropdown menu at the top of the Mantrae interface.
## Creating a Profile
To create a new profile, follow these steps:
1. **Open the Profile Dropdown**: In the top navigation bar, open the profile dropdown and select **Create New Profile**.
2. **Set Profile Details**:
- **Profile Name**: Enter a unique name for this profile (e.g., `default`, `staging`, `production`).
- **Traefik Instance URL**: Provide the URL for the Traefik instance you want this profile to connect to.
- For example, if you’re running Traefik on Docker on the same host, use `http://traefik:8080`.
- **Basic Auth (Optional)**: If your Traefik instance requires basic authentication, provide the credentials here.
Once saved, this profile will serve as a space where you can manage routers and middlewares specifically for this Traefik instance.
## Using Profiles with Traefik
Each profile in Mantrae has its own API endpoint, allowing Traefik to fetch the correct configuration based on the active profile.
- **Example**: If your profile name is `default`, the corresponding API endpoint in Mantrae will be:
`/api/default`
Configure Traefik to use this endpoint to pull configuration details specific to this profile. E.g. by using the static config:
```yaml
# Using the static config:
providers:
http:
endpoint: "http://mantrae:3000/api/<profile-name>"
# Optional if you enabled basic auth on mantrae itself
headers:
Authorization: Basic <base64 encoded username:password>
# Or as command in docker compose:
traefik:
image: docker.io/traefik:latest
container_name: traefik
command:
- --providers.http.endpoint=http://mantrae:3000/api/<profile-name>
- ... other commands
```

34
docs/docs/usage/02-dns.md
View File

@@ -1,34 +0,0 @@
---
sidebar_position: 2
---
# DNS
In Mantrae, you can set up DNS providers and configure them to automatically manage domain entries for your routers. This section explains how to add DNS providers, link them to routers, and manage DNS records for seamless integration with Traefik.
## Supported DNS Providers
Mantrae currently supports the following DNS providers:
- **Cloudflare**
- **PowerDNS**
- **Technitium**
### Adding a DNS Provider
To add a DNS provider:
1. Navigate to the **DNS** section (globe icon).
2. Select your provider from the available options and enter the necessary credentials.
3. For PowerDNS and Technitium you also need to set the endpoint where they are running.
4. Save the provider. It will now be available for selection when configuring routers.
### Setting a DNS Provider in Routers
Once a DNS provider is configured, you can assign it to specific routers. When you assign a DNS provider to a router:
- Mantrae will automatically attempt to add the router's domain name to the configured DNS provider.
- **Duplicate Check**: If the domain already exists, Mantrae will skip it to avoid overwriting any existing records.
- **Default**: Setting a provider as "Default" will automatically use it on newly created routers, so if no DNS provider is assigned to the router, Mantrae will use the default DNS provider.
> **Note**: This DNS automation only applies if no entry for the domain exists. Ensure your domain records are unique to prevent conflicts.

47
docs/docs/usage/03-agents.md
View File

@@ -1,47 +0,0 @@
---
sidebar_position: 3
---
# Agents
Agents extend the functionality of your Traefik setup by allowing you to collect Docker container information from machines that don’t have Traefik installed. This way, you can apply Traefik labels on containers across multiple hosts, and the agent will sync this data with your main Traefik instance.
## How Agents Work
An agent is a standalone binary that runs on any machine where you want to manage remote containers. Each agent:
- Collects Docker container metadata and Traefik labels.
- Communicates with the Mantrae server, sending back container info for unified management.
## Setting Up an Agent
### Step 1: Set the Server Address
In the settings, specify the **server address** for your Mantrae server. This address must be accessible by the agent to ensure successful communication.
> **Note**: If Mantrae is hosted on a public IP or domain (e.g., `https://mantrae.example.com`), configure this as the server address so agents can connect reliably.
### Step 2: Generate and Copy the Agent Token
1. In the Mantrae UI, navigate to the **Agents** tab.
2. Add a new agent by clicking the **Add Agent** button.
3. Copy the generated agent token by using the **Copy Token** button.
### Step 3: Run the Mantrae Agent
1. Download the agent binary for your platform. (Or start the agent in a container.)
2. Run the agent with the token using the following command:
```bash
TOKEN=YOUR_TOKEN ./mantrae-agent
```
3. Ensure that the machine running the agent has Docker installed, as it will gather container details from the Docker daemon.
## Use Case: Traefik Labels on Remote Hosts
Once the agent is running, you can set Traefik labels on containers located on the agent’s host machine as you normally would for Traefik. The agent collects these labels and sends them to the Mantrae server, where they are applied to the main Traefik instance.
This setup allows you to centralize routing configurations across multiple hosts without installing Traefik on each machine.
---
Using agents, you can scale your Traefik configuration effortlessly, managing containers across multiple machines from a single, centralized Mantrae server.

65
docs/docs/usage/04-environment.md
View File

@@ -1,65 +0,0 @@
---
sidebar_position: 4
---
# Environment Variables
Mantrae provides several command-line flags and environment variables to
configure the application. This guide details each option and its purpose.
## Command-Line Arguments
You can use the following flags to customize the behavior of Mantrae:
| Flag | Type | Default | Description |
| ---------- | ------ | ------- | ------------------------------------------------------------------------ |
| `-version` | `bool` | `false` | Prints the current version of Mantrae and exits. |
| `-update` | `bool` | `false` | Updates Mantrae to the latest version. (Doesn't work inside a container) |
## Environment Variables
Environment variables can be used to set up Mantrae and configure its settings.
Below is a list of the supported environment variables.
### Core Configuration
| Variable | Default | Description |
| -------- | ------- | ------------------------------------------------ |
| `SECRET` | | Secret key required for secure access. Required! |
### Server Configuration
| Variable | Default | Description |
| ------------------- | ------------------ | ---------------------------------------------------------- |
| `SERVER_HOST` | `0.0.0.0` | Host address the server will bind to |
| `SERVER_PORT` | `3000` | Port which Mantrae will listen on |
| `SERVER_URL` | `http://127.0.0.1` | The public URL of the Mantrae server for agent connections |
| `SERVER_BASIC_AUTH` | `false` | Enables basic authentication for the Mantrae server |
### Traefik Configuration
| Variable | Default | Description |
| ------------------ | --------- | ------------------------------- |
| `TRAEFIK_PROFILE` | `default` | Traefik profile name |
| `TRAEFIK_URL` | | Traefik API URL |
| `TRAEFIK_USERNAME` | | Traefik authentication username |
| `TRAEFIK_PASSWORD` | | Traefik authentication password |
| `TRAEFIK_TLS` | `false` | Enable TLS for Traefik |
### Example Usage
To run Mantrae with custom environment variables:
```bash
export SECRET="your-secret-key"
export SERVER_PORT="4000"
export ADMIN_PASSWORD="secure-password"
./mantrae
```
### Important Notes
- **SECRET** is a required environment variable and must be set; otherwise, the
application will not start.
- Set **SERVER_URL** to the publicly accessible URL of Mantrae to ensure agents
can connect to it.

69
docs/docs/usage/05-backups.md
View File

@@ -1,69 +0,0 @@
---
sidebar_position: 5
---
# Backups & Restoration
Mantrae provides robust backup and restoration capabilities to help you manage and protect your configuration. You can perform both database backups and import configurations from Traefik dynamic config files.
## Automatic Backups
Mantrae automatically creates backups of your database according to the configuration settings detailed in the [Environment](./04-environment.md) documentation. These backups ensure you can recover your configuration if needed.
## Manual Backups & Restoration
### Database Backups
From the Settings page, you can:
- Create an immediate backup of your entire database
- Download existing backup files
- Restore from a previous backup file
> **Note**: Restoring from a database backup will completely reset your Mantrae instance, replacing all existing data including profiles, routers, services, and middlewares.
### Traefik Configuration Import
For more flexible configuration management, Mantrae supports importing from Traefik dynamic configuration files:
1. Navigate to the Settings page
2. Select "Import Configuration"
3. Choose your Traefik YAML/JSON configuration file
4. Review the changes and confirm
Key benefits of configuration import:
- Non-destructive operation - existing data remains intact
- Merges new configuration with existing setup
- Overwrites only components with matching names
- Preserves your current profiles and settings
Example of an importable Traefik configuration:
```yaml
http:
routers:
my-router:
rule: "Host(`example.com`)"
service: "my-service"
middlewares:
- "auth-middleware"
services:
my-service:
loadBalancer:
servers:
- url: "http://localhost:8080"
middlewares:
auth-middleware:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
```
## Best Practices
1. Regular backups: Although Mantrae handles automatic backups, consider creating manual backups before major changes
2. Configuration versioning: Store your Traefik configurations in version control for additional safety
3. Test restorations: Periodically verify your backup files can be successfully restored

2
docs/docs/usage/_category_.json
View File

@@ -4,6 +4,6 @@
"collapsed": false,
"link": {
"type": "generated-index",
"description": "Getting started with Mantrae"
"description": "Learn how to use Mantrae to manage your Traefik configurations"
}
}

128
docs/docs/usage/agents.md Normal file
View File

@@ -0,0 +1,128 @@
---
sidebar_position: 4
---
# Agents
Agents in Mantrae extend your Traefik setup by enabling automatic configuration discovery from remote Docker hosts. Instead of manually defining routers in the web UI, you can label your containers with standard Traefik labels, and the agent will automatically synchronize this information with your Mantrae server.
## How Agents Work
An agent is a lightweight binary that runs on any machine where you want to manage Docker containers. Each agent:
- Discovers Docker containers and their Traefik labels on the local machine
- Communicates with the Mantrae server to synchronize container information
- Automatically creates routers, services, and middlewares based on container labels
- Updates the Mantrae server when containers are added, removed, or changed
## Setting Up an Agent
### Step 1: Create an Agent in Mantrae
1. Log into the Mantrae web interface
2. Navigate to the "Agents" section
3. Click "Add Agent"
### Step 2: Copy the Agent Token
After creating the agent, you'll see a configuration section with:
- Agent Token (automatically generated)
- Docker Run command
- Docker Compose configuration
Copy the agent token for the next step.
### Step 3: Deploy the Agent
You can run the agent in several ways:
#### Option 1: Direct Binary Execution
1. Download the agent binary for your platform from the [releases page](https://github.com/mizuchilabs/mantrae/releases)
2. Run the agent with the token:
```bash
TOKEN=YOUR_AGENT_TOKEN HOST=https://mantrae.example.com ./mantrae-agent
```
#### Option 2: Docker Run
Use the pre-generated Docker run command from the agent configuration page:
```bash
docker run -d \
--name mantrae-agent \
-e TOKEN=YOUR_AGENT_TOKEN \
-e HOST=https://mantrae.example.com \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
ghcr.io/mizuchilabs/mantrae-agent:latest
```
#### Option 3: Docker Compose
Use the pre-generated Docker Compose configuration:
```yaml
services:
mantrae-agent:
image: ghcr.io/mizuchilabs/mantrae-agent:latest
container_name: mantrae-agent
network_mode: host
environment:
- TOKEN=YOUR_AGENT_TOKEN
- HOST=https://mantrae.example.com
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
restart: unless-stopped
```
## Using Traefik Labels with Agents
Once the agent is running, you can label your containers as you normally would with Traefik. The agent will automatically collect these labels and synchronize them with the Mantrae server.
### Example HTTP Service
```yaml
services:
whoami:
image: containous/whoami:latest
ports:
- "80:80"
labels:
- "traefik.enable=true"
- "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)"
- "traefik.http.routers.whoami.entrypoints=websecure"
- "traefik.http.routers.whoami.tls=true"
- "traefik.http.services.whoami.loadbalancer.server.port=80"
```
## Agent Configuration Options
The agent supports several environment variables for configuration:
| Variable | Description | Default |
|----------|-------------|---------|
| `TOKEN` | Agent token from Mantrae server | Required |
| `HOST` | Mantrae server URL | http://localhost:3000 |
## Network Configuration
Agents can automatically detect their network configuration:
1. **Public IP Detection**: Agents will automatically detect their public IP address
2. **Private Network**: For internal networks, agents can use their private IP
3. **Manual Override**: You can manually specify the IP address that should be used for services
This information is visible in the agent details page in the Mantrae web interface.
## Monitoring Agent Status
In the Mantrae web interface, you can:
- View the status of all agents (online/offline)
- See when each agent last synchronized
- View the containers discovered by each agent
- Rotate agent tokens for security
## Security Considerations
- Each agent has a unique token that should be kept secret
- Tokens can be rotated at any time from the web interface
- Agents only need read-only access to the Docker socket

115
docs/docs/usage/backups.md Normal file
View File

@@ -0,0 +1,115 @@
---
sidebar_position: 5
---
# Backups & Restoration
Mantrae provides robust backup and restoration capabilities to help you manage and protect your configuration. You can perform both database backups and import configurations from Traefik dynamic config files.
## Automatic Backups
Mantrae automatically creates backups of your database according to the configuration settings detailed in the [Environment](./environment.md) documentation. These backups ensure you can recover your configuration if needed.
By default, backups are created daily and retained for 30 days. You can customize the backup schedule and retention period through environment variables.
## Manual Backups & Restoration
### Database Backups
From the Settings page, you can:
- Create an immediate backup of your entire database
- Download existing backup files
- Restore from a previous backup file
> **Note**: Restoring from a database backup will completely reset your Mantrae instance, replacing all existing data including profiles, routers, services, and middlewares.
### Traefik Configuration Import
For more flexible configuration management, Mantrae supports importing from Traefik dynamic configuration files:
1. Navigate to the Settings page
2. Select "Import Configuration"
3. Choose your Traefik YAML/JSON configuration file
4. Review the changes and confirm
Key benefits of configuration import:
- Non-destructive operation - existing data remains intact
- Merges new configuration with existing setup
- Overwrites only components with matching names
- Preserves your current profiles and settings
Example of an importable Traefik configuration:
```yaml
http:
routers:
my-router:
rule: "Host(`example.com`)"
service: "my-service"
middlewares:
- "auth-middleware"
entryPoints:
- "websecure"
tls: {}
services:
my-service:
loadBalancer:
servers:
- url: "http://localhost:8080"
middlewares:
auth-middleware:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
```
## Backup Storage
Backups can be stored in multiple locations:
### Local Storage
By default, backups are stored in the `data/backups/` directory within the Mantrae installation.
### S3-Compatible Storage
Configure S3-compatible storage for cloud backups:
```bash
STORAGE_TYPE=s3
STORAGE_S3_ENDPOINT=https://s3.amazonaws.com
STORAGE_S3_REGION=us-east-1
STORAGE_S3_BUCKET=mantrae-backups
STORAGE_S3_ACCESS_KEY=your-access-key
STORAGE_S3_SECRET_KEY=your-secret-key
STORAGE_S3_PATH=backups/
```
## Backup Configuration
Customize backup behavior through environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `BACKUP_SCHEDULE` | `0 2 * * *` | Cron expression for backup schedule (daily at 2 AM) |
| `BACKUP_RETENTION` | `30` | Number of days to keep backups |
| `BACKUP_AUTO_ENABLED` | `true` | Enable automatic backups |
## Best Practices
1. **Regular backups**: Although Mantrae handles automatic backups, consider creating manual backups before major changes
2. **Configuration versioning**: Store your Traefik configurations in version control for additional safety
3. **Test restorations**: Periodically verify your backup files can be successfully restored
4. **Off-site storage**: Download and store backups in a secure off-site location
5. **Multiple backup strategies**: Use both automatic backups and configuration imports for comprehensive protection
## Backup Security
- Backup files contain sensitive configuration data
- All backups are stored with appropriate file permissions
- When using S3 storage, data is transmitted securely
- Consider encrypting backup files when storing them off-site

77
docs/docs/usage/dns.md Normal file
View File

@@ -0,0 +1,77 @@
---
sidebar_position: 2
---
# DNS Providers
In Mantrae, you can set up DNS providers and configure them to automatically manage domain entries for your routers. This section explains how to add DNS providers, link them to routers, and manage DNS records for seamless integration with Traefik.
## Supported DNS Providers
Mantrae currently supports the following DNS providers:
- **Cloudflare**
- **PowerDNS**
- **Technitium**
Each provider can be configured within a profile, allowing you to use different DNS providers for different environments.
## Adding a DNS Provider
To add a DNS provider:
1. **Select Profile**: Ensure you're working with the correct profile
2. Navigate to the **DNS** section (globe icon)
3. Click "Add Provider"
4. Select your provider from the available options and enter the necessary credentials
5. For PowerDNS and Technitium you also need to set the endpoint where they are running
6. Save the provider. It will now be available for selection when configuring routers
## Provider-Specific Configuration
### Cloudflare
For Cloudflare, you'll need:
- **API Token**: A scoped API token with DNS permissions
### PowerDNS
For PowerDNS, you'll need:
- **API URL**: The URL to your PowerDNS API
- **API Key**: The API key for authentication
### Technitium
For Technitium DNS, you'll need:
- **API URL**: The URL to your Technitium DNS API
- **API Key**: The API key for authentication
- **Zone Type**: The zone type can be either `primary` or `forwarder`
## Setting a DNS Provider in Routers
Once a DNS provider is configured, you can assign it to specific routers. When you assign a DNS provider to a router:
- Mantrae will automatically attempt to add the router's domain name to the configured DNS provider
- **Duplicate Check**: If the domain already exists, Mantrae will skip it to avoid overwriting any existing records
- **Default**: Setting a provider as "Default" will automatically use it on newly created routers, so if no DNS provider is assigned to the router, Mantrae will use the default DNS provider
## Automatic Certificate Management
When using DNS providers with Traefik:
1. Traefik will automatically request certificates for configured domains
2. Mantrae will provide the DNS provider credentials to Traefik through the dynamic configuration
3. Traefik will create the necessary DNS challenge records
4. Certificates will be automatically renewed as needed
## Security Considerations
- DNS provider credentials are stored encrypted in the database
- Each profile can have its own set of DNS providers
- Credentials are only accessible to the profile they belong to
- API tokens should follow the principle of least privilege
> **Note**: This DNS automation only applies if no entry for the domain exists. Ensure your domain records are unique to prevent conflicts.

35
docs/docs/usage/environment.md Normal file
View File

@@ -0,0 +1,35 @@
---
sidebar_position: 4
---
# Environment Variables
Mantrae provides several command-line flags and environment variables to configure the application. This guide details each option and its purpose.
## Command-Line Arguments
You can use the following flags to customize the behavior of Mantrae:
| Flag | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `-version` | `bool` | `false` | Prints the current version of Mantrae and exits. |
| `-update` | `bool` | `false` | Updates Mantrae to the latest version. (Doesn't work inside a container) |
## Environment Variables
Environment variables can be used to set up Mantrae and configure its settings. Below is a list of the supported environment variables.
### Core Configuration
| Variable | Default | Description |
| -------- | ------- | ----------- |
| `SECRET` | | Secret key required for secure access (required) |
| `ADMIN_PASSWORD` | | Admin password for the web interface (will be auto-generated if not set) |
| `LOG_LEVEL` | `info` | Logging level (debug, info, warn, error) |
| `LOG_FORMAT` | `text` | Log format (text, json) |
### Important Notes
- **SECRET** is a required environment variable and must be set; otherwise, the application will not start.
- Database migrations are automatically applied on startup.
- In production, always use a strong secret and HTTPS.

98
docs/docs/usage/profiles.md Normal file
View File

@@ -0,0 +1,98 @@
---
sidebar_position: 3
---
# Profiles
Profiles in Mantrae allow you to manage multiple Traefik instances from a single interface. Each profile represents a distinct Traefik configuration environment, such as development, staging, or production.
## Understanding Profiles
A profile is a logical grouping of:
- Routers (HTTP, TCP, UDP)
- Services (HTTP, TCP, UDP)
- Middlewares (HTTP, TCP)
- Entry Points
- Servers Transports
- DNS Providers
- Agents
Each profile has its own dynamic configuration endpoint that Traefik instances can consume.
## Creating a Profile
To create a new profile:
1. **Access the Web UI**: Log into Mantrae at `http://localhost:3000`
2. **Navigate to Profiles**: Click on the profile dropdown in the top navigation bar
3. **Create New Profile**: Select "Create New Profile"
4. **Configure Profile Details**:
- **Name**: A unique identifier for this profile (e.g., `production`, `staging`)
- **Description**: Optional description of the profile's purpose
- **Token**: A security token for accessing this profile's configuration (auto-generated)
Once saved, this profile will serve as a dedicated space for managing Traefik configurations specific to this environment.
## Using Profiles with Traefik
Each profile in Mantrae exposes a unique API endpoint that Traefik can use to fetch its dynamic configuration.
### Dynamic Configuration Endpoint
For a profile named `production`, the dynamic configuration endpoint would be:
```
http://mantrae:3000/api/production?token=GENERATED_TOKEN
```
### Configure Traefik to Use Mantrae
Configure your Traefik instance to use Mantrae as its dynamic configuration provider:
#### Using Static Configuration File
```yaml
providers:
http:
endpoint: "http://mantrae:3000/api/production?token=GENERATED_TOKEN"
pollInterval: "5s" # Optional: polling interval for configuration updates
```
#### Using Command Line Arguments
In Docker Compose:
```yaml
traefik:
image: traefik:latest
container_name: traefik
command:
- --providers.http.endpoint=http://mantrae:3000/api/production?token=GENERATED_TOKEN
- --providers.http.pollInterval=5s
# ... other Traefik configuration
```
#### Using Environment Variables
```bash
TRAEFIK_PROVIDERS_HTTP_ENDPOINT=http://mantrae:3000/api/production?token=GENERATED_TOKEN
TRAEFIK_PROVIDERS_HTTP_POLLINTERVAL=5s
```
## Profile-Specific Configuration
Each profile maintains its own separate configuration space. This means:
- Routers created in the `production` profile are completely isolated from those in the `staging` profile
- Services, middlewares, and other components are profile-specific
- Agents can be assigned to specific profiles
- DNS providers can be configured per profile
## Managing Multiple Profiles
You can easily switch between profiles using the profile dropdown in the Mantrae web interface:
1. Click the current profile name in the top navigation bar
2. Select the profile you want to work with from the dropdown
3. All subsequent actions will apply to the selected profile
This allows you to manage multiple Traefik environments without switching between different Mantrae instances.

7
docs/docusaurus.config.ts
View File

@@ -29,6 +29,7 @@ const config: Config = {
{
docs: {
sidebarPath: "./sidebars.ts",
routeBasePath: "/",
},
blog: {
showReadingTime: true,
@@ -87,11 +88,11 @@ const config: Config = {
items: [
{
label: "Introduction",
to: "/docs/intro",
to: "/intro",
},
{
label: "Usage",
to: "/docs/category/usage",
to: "/usage/profiles",
},
],
},
@@ -126,4 +127,4 @@ const config: Config = {
} satisfies Preset.ThemeConfig,
};
export default config;
export default config;

16253
docs/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

10
docs/package.json
View File

@@ -15,8 +15,8 @@
"typecheck": "tsc"
},
"dependencies": {
"@docusaurus/core": "^3.8.0",
"@docusaurus/preset-classic": "^3.8.0",
"@docusaurus/core": "^3.8.1",
"@docusaurus/preset-classic": "^3.8.1",
"@mdx-js/react": "^3.1.0",
"clsx": "^2.1.1",
"prism-react-renderer": "^2.4.1",
@@ -24,9 +24,9 @@
"react-dom": "^18.3.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.8.0",
"@docusaurus/tsconfig": "^3.8.0",
"@docusaurus/types": "^3.8.0",
"@docusaurus/module-type-aliases": "^3.8.1",
"@docusaurus/tsconfig": "^3.8.1",
"@docusaurus/types": "^3.8.1",
"typescript": "~5.6.3"
},
"browserslist": {

11054
docs/pnpm-lock.yaml generated Normal file
View File

File diff suppressed because it is too large Load Diff

48
docs/sidebars.ts
View File

@@ -1,33 +1,25 @@
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
- render a sidebar for each doc of that group
- provide next/previous navigation
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
*/
const sidebars: SidebarsConfig = {
// By default, Docusaurus generates a sidebar from the docs folder structure
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
// But you can create a sidebar manually
/*
tutorialSidebar: [
'intro',
'hello',
{
type: 'category',
label: 'Tutorial',
items: ['tutorial-basics/create-a-document'],
},
],
*/
tutorialSidebar: [
"intro",
"quickstart",
"installation",
"faq",
"api",
{
type: "category",
label: "Usage",
items: [
"usage/profiles",
"usage/dns",
"usage/agents",
"usage/environment",
"usage/backups",
],
},
],
};
export default sidebars;

2
docs/src/pages/index.tsx
View File

@@ -19,7 +19,7 @@ function HomepageHeader() {
<div className={styles.buttons}>
<Link
className="button button--secondary button--lg"
to="/docs/intro">
to="/intro">
Mantrae Tutorial - 5min ⏱️
</Link>
</div>

6
web/src/lib/components/modals/AgentModal.svelte
View File

@@ -94,9 +94,9 @@
mantrae-agent:
image: ghcr.io/mizuchilabs/mantrae-agent:latest
container_name: mantrae-agent
network_mode: host
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./agent:/data
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
- TOKEN=${item.token}
- HOST=${serverURL}
@@ -106,7 +106,7 @@
const dockerRunText = $derived.by(async () => {
const response = await settingClient.getSetting({ key: 'server_url' });
const serverURL = response.value ?? 'http://127.0.0.1:3000';
return `docker run -d --name mantrae-agent -v /var/run/docker.sock:/var/run/docker.sock -v ./agent:/data -e TOKEN=${item.token} -e HOST=${serverURL} ghcr.io/mizuchilabs/mantrae-agent:latest`;
return `docker run -d --name mantrae-agent --network host -v /var/run/docker.sock:/var/run/docker.sock:ro -e TOKEN=${item.token} -e HOST=${serverURL} ghcr.io/mizuchilabs/mantrae-agent:latest`;
});
const dockerComposeClipboard = new UseClipboard();