Docker and Linux Deployment

中文 | English

Docker is optional. If you prefer running DiceFrame directly on your computer, Windows, macOS, and Linux can still start it with:

pip install -r requirements.txt
python web_server.py

The container stores runtime data in /app/data; Compose maps it to ./data in the project directory. Saves, settings, access credentials, and plugin runtime data remain on the host when the image is rebuilt. User-installed plugin source code lives under /app/data/plugin-packages/ and is preserved with the data volume across image upgrades or container rebuilds; /app/plugins holds only built-in and example plugins and is updated with the image.

If only the browser application should be hosted on Cloudflare Pages or another static host while the backend remains on your own device, see Deploying the WebUI Separately. That mode is optional and does not change the Windows, Linux, or Docker deployment described here.

Quick Start

Using the published image:

Compose commands must be run from a DiceFrame deployment directory containing docker-compose.yml. Clone the repository or download and extract a source archive from GitHub Releases, then enter its root directory:

git clone --depth 1 https://github.com/diceframe/diceframe.git
cd diceframe
test -f docker-compose.yml

For an extracted source archive, replace cd diceframe with its actual directory. The final command should produce no output when the directory is correct.

After starting DiceFrame, add providers under Manage → Settings → Model API → AI Providers, then assign models under Manage → Settings → Model Routing. .env configures deployment options such as ports; old AI endpoint/key/model environment variables are no longer activated or automatically converted. See the user guide for provider setup.

cp .env.example .env
# Edit .env only for deployment options such as the host port.
docker compose pull
docker compose up -d

The default Compose setup and the latest tag track stable releases only. Preview builds are also published to GHCR and Docker Hub, but require a full explicit version tag and never replace latest:

docker pull ghcr.io/diceframe/diceframe:2.3.0-beta.1
docker pull falconku/diceframe:2.3.0-beta.1

For optional vector memory, first save the embedding provider's address, key and model catalog under Manage → Settings → Model API. Then enable Vector Memory under Model Routing, select that provider/model, set the maximum input if needed and test the connection. In Docker, an Ollama provider can use http://host.docker.internal:11434 or another reachable host address; 127.0.0.1 inside the container refers to the container itself. Local providers may leave the key empty. Configure AI roles in the WebUI rather than through old embedding environment variables.

Open http://localhost:9876. To change the host port:

DICEFRAME_HTTP_PORT=8080

Then open http://localhost:8080. The internal port remains 9876, keeping WebUI, plugin-host, and internal API addresses stable.

Common Commands

Run these commands from the same deployment directory:

docker compose pull
docker compose up -d
docker compose logs -f
docker compose down

no configuration file provided: not found is not an image failure; it means the current directory has no Compose file. Change to the original deployment directory and verify that docker-compose.yml exists. If the container was originally created with docker run or a NAS container manager, these Compose commands do not apply. Preserve the original ports, environment variables, and data mount, pull the new image, and recreate the container through the original deployment method.

To rebuild an image after changing the local source:

docker compose up -d --build
docker compose build --no-cache

Managed-update-capable Docker/NAS installations with a compatible Python/system runtime can apply ordinary application updates from Manage → Settings → About; failed candidate validation restores the previous program and its readable data. Legacy baseline images or base-runtime changes require pulling an image and recreating the container with its original data/ mount, ports, and environment. Back up the complete data/ directory, including data/_updater, before upgrading. See Application Updates for installation-specific steps, retained datasets, and rollback behavior.

Data and Secrets

• ./data is runtime storage and is excluded by .gitignore and .dockerignore.
• .env contains machine-specific deployment settings and is also excluded.
• .env.example is public and must not contain real API keys, tokens, group IDs, or private addresses.
• Without TRPG_ACCESS_TOKEN, DiceFrame generates an initial access password in ./data/access_token.txt.
• To reset a forgotten WebUI password, create ./data/reset_access_password.txt, put the new password inside, and restart. DiceFrame removes the file after a successful reset.

QQ / NapCat

The Docker deployment uses the same built-in plugin host. When enabled, QQ/NapCat runs as a child process inside the main service container.

1. Start the WebUI with docker compose up -d.
2. Enable QQ / NapCat under Manage → Plugins.
3. If NapCat runs outside the container, use a host or NAS address reachable from the container for NAPCAT_HOST and NAPCAT_PORT.

The built-in QQ plugin does not require a manually entered DiceFrame Bot API Token. DiceFrame generates and persists it. An external MaiBot bridge copies the value from Manage → Settings → Bot API.

Optional initial values:

# Optional fixed global Bot API Token; leave empty for automatic generation.
TRPG_BOT_TOKEN=
NAPCAT_HOST=192.168.1.10
NAPCAT_PORT=3001
NAPCAT_TOKEN=

Inside Linux containers, 127.0.0.1 refers to the container itself. For NapCat on the host, use the host LAN address or the mapped host.docker.internal name.

Using Desktop and Docker Data

Direct desktop use reads the project's data/; Compose maps the same ./data. Switching between them therefore keeps the same saves and settings.

For a separate Docker environment:

TRPG_DATA_DIR=./data-docker docker compose up

or change the Compose volume:

volumes:
  - ./data-docker:/app/data