Deployment Guide
Tip
When to read this: When the bot needs to run long-term—Docker deployment, systemd / Supervisor process management, reverse proxy and SSL, backup and upgrade are all covered here. Skip this section if you are only doing local development and debugging.
After developing the bot, deployment is just the beginning. This guide covers three deployment methods (Docker / systemd / Supervisor), as well as reverse proxy, security hardening, and backup.
Docker Deployment (Recommended)
ErisPulse provides an official Docker image, which includes the ErisPulse framework and the Dashboard management panel, supporting linux/amd64 and linux/arm64 architectures.
Quick Start
# Pull the image
docker pull erispulse/erispulse:latest
# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/ErisPulse/ErisPulse/main/docker-compose.yml
# Set the Dashboard login token and start the container
ERISPULSE_DASHBOARD_TOKEN=your-token docker compose up -d
After starting, access http://localhost:8000/Dashboard and log in using the set token as the password.
Domestic Image Acceleration
If Docker Hub is inaccessible, you can use GitHub Container Registry to pull the image:
docker pull ghcr.io/erispulse/erispulse:latest
When using the ghcr.io image, you need to modify the image in docker-compose.yml:
services:
erispulse:
image: ghcr.io/erispulse/erispulse:latest
docker-compose.yml
services:
erispulse:
image: erispulse/erispulse:${ERISPULSE_TAG:-latest}
container_name: ${CONTAINER_NAME:-erispulse}
ports:
- "${ERISPULSE_PORT:-8000}:8000"
volumes:
- ./config:/app/config
# Persist Python package directory
- ./config/.packages:/usr/local/lib/python3.13/site-packages
environment:
- TZ=${TZ:-Asia/Shanghai}
- LANG=${LANG:-en_US.UTF-8}
- ERISPULSE_LANG=${ERISPULSE_LANG:-}
- ERISPULSE_DASHBOARD_TOKEN=${ERISPULSE_DASHBOARD_TOKEN:-}
init: true
# Graceful shutdown is handled by framework signal processing (SIGTERM), this only controls the grace period
stop_grace_period: 30s
restart: on-failure:5
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/ping')"]
interval: 30s
timeout: 5s
start_period: 20s
retries: 3
The above is consistent with the root docker-compose.yml (the root version also has comments on image acceleration and environment variables), it is recommended to directly download and use it.
Environment Variables
| Variable | Default | Description |
|---|---|---|
ERISPULSE_PORT |
8000 |
Dashboard port mapping |
ERISPULSE_TAG |
latest |
Image tag (set to a specific version number if you want to lock the version) |
CONTAINER_NAME |
erispulse |
Container name (useful for distinguishing instances in multi-instance deployment) |
ERISPULSE_DASHBOARD_TOKEN |
auto-generated | Dashboard login token (strongly recommended to set) |
TZ |
Asia/Shanghai |
Timezone |
LANG |
en_US.UTF-8 |
System language, automatically detects the startup interface language |
ERISPULSE_LANG |
empty | Force startup interface language: zh / zh_TW / en / ja / ru (overrides LANG) |
Data Persistence
The ./config directory mounts configuration files and the database, including:
config/config.toml— Configuration fileconfig/config.db— SQLite storage databaseconfig/.packages— Persistent Python site-packages volume, saves the framework, adapters, and installed modules (automatically initialized from the image's built-in backup during the first startup; subsequent module installations and framework hot-updates are written to this directory)
Framework upgrade (including pre/rc) and image self-healing: The entrypoint performs a core package integrity self-check each time the container starts. If damaged, it repairs based on the "user-installed version priority" principle—explicitly installed/updated versions (such as pre versions installed in Dashboard) are reinstalled from PyPI at the same version, never silently rolled back to the image's built-in version. Therefore, after Dashboard upgrades the framework, any container restart should maintain the target version.
Dashboard Management Panel
The ErisPulse Docker image includes the Dashboard module, providing a Web-based visual management interface.
Feature Overview
| Feature | Description |
|---|---|
| Dashboard | System overview, CPU/memory monitoring, uptime, event statistics |
| Bot Management | View online status and information of bots on each platform |
| Event Viewer | Real-time event stream, supports filtering by type and platform |
| Log Viewer | Log viewer with filtering by module and level |
| Module Manager | View, load, and unload installed modules and adapters |
| Module Store | Browse remote available packages and install them with one click |
| Config Editor | Edit config.toml online |
| Storage Manager | Browse and edit Key-Value storage data |
| Backup | Export/import configuration and storage data |
| Audit Log | Records all management operations |
Installing Modules via Dashboard
The Dashboard integrates a module store feature, allowing you to:
- Install from the store: Browse the remote module list and install needed modules with one click
- Upload local packages: Directly upload
.whlor.zipfiles for installation, convenient for testing personal development modules
Quick testing workflow for module developers: After deploying with Docker, use the "Upload local package" feature in the Dashboard to directly upload your built
.whlfile for testing, without manual container operations.
Process Supervision and Hard Restart
ErisPulse's hard restart (sdk.hard_restart()) depends on an external supervisor to restart the process when the exit code is 42—the SDK itself does not restart new processes. Production environments must configure a supervisor; otherwise, the process will not automatically recover after a hard restart:
- Docker: The official compose uses
restart: on-failure:5—restarts on any non-zero exit code (overrides the hard restart exit code 42), with a maximum of 5 consecutive restarts to prevent dead loops; unlimited restarts can be set by changing tounless-stopped - systemd:
Restart=on-failure+RestartForceExitStatus=42 - PM2 / supervisord: Add 42 to the list of restartable exit codes
- Pure Python custom supervisor: Use a loop
Popen+ checkreturncode == 42
Complete configuration examples for each supervisor and the exit code 42 contract are available in Startup Flow → Supervisor Guide.
Container Restart (PID 1 Instance)
This feature requires ErisPulse 2.12+.
When the framework runs as the main process (PID 1) inside a container, epsdk restart does not terminate and restart the process—terminating PID 1 causes the container to exit. Instead, send SIGUSR1 to the framework process, which performs an in-process soft restart (component-level, sdk.restart()): ep i <package> newly installed adapters and upgraded module code are immediately hot-reloaded.
- For a full process restart (framework updates, structural configuration changes), restart the container:
docker restart <container> epsdk stopstill means termination for PID 1 instances—the container stops (whether it automatically restarts depends on therestartpolicy)
Health Check
The SDK includes a built-in health check endpoint:
# Health check
curl http://localhost:8000/health
The official docker-compose.yml already includes the following health check; when writing your own compose file, you can refer to it:
services:
erispulse:
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/ping')"]
interval: 30s
timeout: 5s
start_period: 20s
retries: 3
Reverse Proxy
If you need to expose the Dashboard via a reverse proxy like Nginx:
server {
listen 80;
server_name bot.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
# WebSocket support (required for Dashboard real-time event streams)
location /Dashboard/ws {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
SSL can be enabled using Let's Encrypt:
sudo certbot --nginx -d bot.example.com
Manual Deployment (pip)
If you don't use Docker, you can also deploy manually.
Production Configuration
# config/config.toml
[ErisPulse.server]
host = "0.0.0.0"
port = 8000
[ErisPulse.logger]
level = "INFO"
log_files = ["app.log"]
memory_limit = 5000
[ErisPulse.framework]
enable_lazy_loading = true
systemd (Linux)
Create /etc/systemd/system/erispulse-bot.service:
[Unit]
Description=ErisPulse Bot
After=network.target
[Service]
Type=simple
User=bot
WorkingDirectory=/opt/erispulse-bot
ExecStart=/opt/erispulse-bot/venv/bin/epsdk run main.py
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
Manage the service:
sudo systemctl daemon-reload
sudo systemctl start erispulse-bot
sudo systemctl enable erispulse-bot
sudo journalctl -u erispulse-bot -f
Supervisor
Create /etc/supervisor/conf.d/erispulse-bot.conf:
[program:erispulse-bot]
command=/opt/erispulse-bot/venv/bin/python -m ErisPulse run main.py
directory=/opt/erispulse-bot
user=bot
autostart=true
autorestart=true
stderr_logfile=/var/log/erispulse-bot/err.log
stdout_logfile=/var/log/erispulse-bot/out.log
uv tool Separated Deployment (CLI and Project Environment Isolation)
uv tool install installs epsdk as an independent tool environment, completely isolating the CLI from project dependencies: upgrading the CLI does not touch the project .venv, and project dependency changes do not affect the CLI.
# 1. Install CLI globally (exposes epsdk / ep commands automatically)
uv tool install ErisPulse
# 2. Only include robot dependencies in the project (managed by uv)
cd /opt/erispulse-bot
uv add erispulse ErisPulse-Adapter-Yunhu # Add adapters as needed
# 3. Run with CLI (automatically detects and uses the project .venv interpreter)
epsdk run main.py
Behavior points:
- The target interpreter resolution order for
epsdk run:ERISPULSE_PYTHONenvironment variable → project.venv→ current interpreter; the tool environment itself only hosts the CLI, components (adapters/modules) should be installed in the project.venv epsdk install/uninstall/upgrade/listalso affect the project.venv, not the tool environment- Upgrade CLI:
uv tool upgrade ErisPulse(or directlyepsdk self-update, uv tool environment automatically switches touv tool upgrade); upgrade project dependencies: executeuv sync/uv addin the project directory, both are independent - In server scenarios, the tool environment is managed by uv (use
uv tool listto view,uv tool upgrade --allto batch upgrade), no need to manually maintain global pip packages - If
uv run epsdk ...is used in a directory without a project, it falls into a one-time isolated environment (installed components are not persistent); on servers, always useepsdkdirectly, or firstcdinto the project directory
Security Recommendations
- Set Dashboard Token: Use a strong random token, do not use the default value
- Do Not Expose Ports to Public Internet: Unless using a reverse proxy + SSL, restrict the Dashboard port to the internal network
- Protect Data Directory: The
config/directory contains configuration and database, set appropriate file permissions - Regular Updates: Use
epsdk self-updateor pull the latest Docker image - Do Not Run as Root: Create a dedicated user for manual deployment
- Use Docker Restart Policy: The official compose's
restart: on-failure:5ensures automatic restart after abnormal exit (including hard restart exit code 42) - Disable API Docs Endpoint:
/docs,/redoc,/openapi.jsonare enabled by default without authentication; disable withrouter.disable_docs()when deploying publicly - Webhook Signature Verification: The generated
verify_requestin the scaffold defaults to allowing all requests; implement signature/token verification before integrating public callbacks - Security Model Boundaries: The owner/scope system constrains platform-side users; loaded modules are considered trusted code (scope not configured defaults to allow, modules can register provider), do not load modules from untrusted sources
Multi-Instance Deployment
When running multiple bot instances:
- Each instance uses a separate project directory and
docker-compose.yml - Use different port numbers:
ERISPULSE_PORT=8001 - Use different container names:
container_name: erispulse-bot2
Storage Backend Note: Instances do not share state (session inbox / conversation checkpoints / command cooldown are all instance memory state). The default SQLite is a single-file backend, not suitable for simultaneous access by multiple instances; each instance's
config/directory must be independent. Switching to mysql / postgres only means each instance has its own independent database—current version does not support multi-instance collaboration (shared sessions/load balancing), multiple instances in the same group will respond independently, and deduplication must be handled at the platform or business level.
Updates and Maintenance
Docker Method
# Pull the latest image
docker compose pull
# Restart to use the new image
docker compose up -d
pip Method
epsdk self-update
epsdk upgrade
uv tool Method
# Upgrade CLI tool environment
uv tool upgrade ErisPulse
# Upgrade project dependencies (execute in project directory)
uv sync
Hot Reload Server Configuration at Runtime
After modifying the listening address / port / SSL certificate, no process restart is needed. Call router.reload() in any coroutine:
await sdk.router.reload(port=9000) # Change port
await sdk.router.reload(ssl_cert=new_pem, ssl_key=new_key) # Hot swap certificate (for certificate renewal scenarios)
await sdk.router.reload(host="0.0.0.0", port=9000) # Use current configuration for missing parameters
- Reuse the same FastAPI application, all HTTP / WebSocket / SSE routes registered by modules are retained
- Validate the new configuration (certificate can be constructed, port is available) before switching; if failed, restore service with the old configuration and return
False, ensuringFalsemeans the old service remains available - Return
Falseif the server is not running (usesdk.router.start()for the first startup)
Backup
Regularly back up the config/ directory:
# Docker deployment
tar czf erispulse-backup-$(date +%Y%m%d).tar.gz config/
# Or use the "Backup" feature in the Dashboard to export
Next Steps
- After deployment, want visual management: Install ErisPulse-Dashboard, manage modules, view logs, and edit configurations in the browser
- Suspecting environment issues: First run
epsdk doctorto output a health report, see CLI Command Reference · doctor - To adjust framework and component configurations: Check Configuration File Documentation, environment variable overrides are especially suitable for container deployment