# Docker Installation

Using a prebuilt image is the quickest and easiest way to get started with SillyTavern in Docker. You can pull the latest image from the GitHub Container Registry.

Download the docker-compose.yml file from the GitHub Repository and run the following command in the directory where the file is located. This will pull the latest release image from the GitHub Container Registry and start the container, automatically creating the necessary volumes.

docker compose up

You can edit the file and apply additional customization to suit your needs:

• The default port is 8000. You can change it by modifying the ports section.
• Change the image tag to staging if you want to use the development branch instead of the stable release.
• If you want to adjust the server configuration using environment variables, check the Environment Variables page.

You will need two mandatory directory mappings and a port mapping to allow SillyTavern to function. In the command, replace your selections in the following places:

• CONFIG_PATH - The directory where SillyTavern configuration files will be stored on your host machine
• DATA_PATH - The directory where SillyTavern user data (including characters) will be stored on your host machine
• PLUGINS_PATH - (optional) The directory where SillyTavern server plugins will be stored on your host machine
• EXTENSIONS_PATH - (optional) The directory where global UI extensions will be stored on your host machine

• PUBLIC_PORT - The port to expose the traffic on. This is mandatory, as you will be accessing the instance from outside of its virtual machine container. DO NOT expose this to the internet without implementing a separate service for security.

• SILLYTAVERN_VERSION - On the GitHub Packages page you'll see the list of tagged image versions. The image tag "latest" will keep you up-to-date with the current release. You can also utilize "staging" that points to the nightly image of the respective branch.

1. Open your Command Line
2. Run the following command in a folder where you want to store the configuration and data files:

SILLYTAVERN_VERSION="latest"
PUBLIC_PORT="8000"
CONFIG_PATH="./config"
DATA_PATH="./data"
PLUGINS_PATH="./plugins"
EXTENSIONS_PATH="./extensions"

docker run \
  --name="sillytavern" \
  -p "$PUBLIC_PORT:8000/tcp" \
  -v "$CONFIG_PATH:/home/node/app/config:rw" \
  -v "$DATA_PATH:/home/node/app/data:rw" \
  -v "$EXTENSIONS_PATH:/home/node/app/public/scripts/extensions/third-party:rw" \
  -v "$PLUGINS_PATH:/home/node/app/plugins:rw" \
  ghcr.io/sillytavern/sillytavern:"$SILLYTAVERN_VERSION"

If you want to build the Docker image yourself, you can do so by following these steps. This is useful if you want to customize the image or use it for development purposes.

1. Install Docker by following the Docker installation guide here.

   Do not install Docker Desktop.

2. Follow the steps in Manage Docker as a non-root user in the Docker Post-Installation Guide.
3. Install Git using your package manager.

   • Debian (Ubuntu/Pop! OS/etc.)

     sudo apt install git

   • Arch Linux (Manjaro/EndeavourOS/etc.)

     sudo pacman -S git

   • Fedora, Red Hat Enterprise Linux (RHEL), etc.

     sudo dnf install git

4. Clone the SillyTavern repository.

   • Release (Stable Branch)

     git clone https://github.com/SillyTavern/SillyTavern && cd SillyTavern/docker

   • Staging (Development Branch)

     git clone https://github.com/SillyTavern/SillyTavern -b staging && cd SillyTavern/docker

5. Execute docker compose by running the following command within the Docker folder.

   docker compose up -d

6. Open a new browser and go to http://localhost:8000. You should see SillyTavern load in a few moments.

1. Install Docker Desktop by following the Docker installation guide here.
2. Install Git for Windows.
3. Clone the SillyTavern repository.

   • Release (Stable Branch)

     git clone https://github.com/SillyTavern/SillyTavern && cd SillyTavern/docker

   • Staging (Development Branch)

     git clone https://github.com/SillyTavern/SillyTavern -b staging && cd SillyTavern/docker

4. Execute docker compose by running the following command within the Docker folder.

   docker compose up -d

5. Open a new browser and go to http://localhost:8000. You should see SillyTavern load in a few moments.

1. Install Docker Desktop by following the Docker installation guide here.

2. Install git using Homebrew.

   brew install git

3. Clone the SillyTavern repository.

   • Release (Stable Branch)

     git clone https://github.com/SillyTavern/SillyTavern && cd SillyTavern/docker

   • Staging (Development Branch)

     git clone https://github.com/SillyTavern/SillyTavern -b staging && cd SillyTavern/docker

4. Execute docker compose by running the following command within the Docker folder.

   docker compose up -d

5. Open a new browser and go to http://localhost:8000. You should see SillyTavern load in a few moments.

SillyTavern's configuration file (config.yaml) will be located within the config folder. Configuring the config file should be no different than configuring it without Docker, however you will need to run nano or a code editor with administrator rights in order to save your changes.

docker compose restart sillytavern

SillyTavern's data folder will be within the data folder. Backing up your files should be easy to do, however, restoring or adding content into it may require you to do so with administrator rights.

Running plugins like HoYoWiki-Scraper-TS or SillyTavern-Fandom-Scraper within Docker is no different from running it on your system without Docker, however we will need to do a slight modification to the Docker Compose script in order to do so.

1. Using nano or a code editor, open docker-compose.yml and add the following line below volumes.

       volumes:
           - "./config:/home/node/app/config"
           - "./data:/home/node/app/data"
           - "./plugins:/home/node/app/plugins"

2. Create a new folder within the docker folder called plugins.
3. Follow your plugin's instructions on installing the plugin.

4. Using nano or a code editor with administrator rights, open config.yaml (within the config folder) and enable enableServerPlugins

   enableServerPlugins: true

5. Restart the Docker container.

   docker compose restart sillytavern

By default, the container runs as root. If you want files created in mounted volumes to be owned by a specific host user (for example, to avoid root-owned files), you can enable non-root mode.

Set PUID and PGID environment variables to the UID/GID you want the container to use. The entrypoint will update ownership of required directories and then run the server as the mapped user.

Docker Compose example:

services:
  sillytavern:
    environment:
      - PUID=1000
      - PGID=1000

Docker CLI example:

docker run \
  --name="sillytavern" \
  -e PUID=1000 \
  -e PGID=1000 \
  -p "$PUBLIC_PORT:8000/tcp" \
  -v "$CONFIG_PATH:/home/node/app/config:rw" \
  -v "$DATA_PATH:/home/node/app/data:rw" \
  -v "$EXTENSIONS_PATH:/home/node/app/public/scripts/extensions/third-party:rw" \
  -v "$PLUGINS_PATH:/home/node/app/plugins:rw" \
  ghcr.io/sillytavern/sillytavern:"$SILLYTAVERN_VERSION"

You can also run the container as a specific user with Docker's --user flag. In this mode, the container cannot automatically fix permissions, so ensure your mounted volumes are already writable by the UID/GID you provide.

docker run \
  --name="sillytavern" \
  --user 1000:1000 \
  -p "$PUBLIC_PORT:8000/tcp" \
  -v "$CONFIG_PATH:/home/node/app/config:rw" \
  -v "$DATA_PATH:/home/node/app/data:rw" \
  -v "$EXTENSIONS_PATH:/home/node/app/public/scripts/extensions/third-party:rw" \
  -v "$PLUGINS_PATH:/home/node/app/plugins:rw" \
  ghcr.io/sillytavern/sillytavern:"$SILLYTAVERN_VERSION"

The Docker image includes a built-in healthcheck mechanism that monitors the SillyTavern server's responsiveness. This is useful for container orchestration systems (like Docker Compose, Kubernetes, or Docker Swarm) to detect and automatically restart unresponsive containers.

The healthcheck uses a heartbeat file mechanism:

1. When enabled, the SillyTavern server periodically writes a timestamp to a heartbeat.json file in the data directory.
2. The healthcheck script (src/healthcheck.js) verifies that the heartbeat file exists and was recently updated.
3. If the heartbeat file is missing or too old (more than 2 missed intervals), the container is marked as unhealthy.

The healthcheck is controlled by the SILLYTAVERN_HEARTBEATINTERVAL environment variable (or heartbeatInterval in config.yaml). This value specifies the interval in seconds between heartbeat writes.

• Default: 0 (disabled)
• Recommended: 30 seconds when using Docker healthchecks

The default docker-compose.yml file includes healthcheck configuration with the heartbeat enabled:

services:
  sillytavern:
    environment:
      - SILLYTAVERN_HEARTBEATINTERVAL=30
    healthcheck:
      test: ["CMD", "node", "src/healthcheck.js"]
      interval: 30s
      timeout: 10s
      start_period: 20s
      retries: 3

You can check the health status of your container using:

docker inspect --format='{{.State.Health.Status}}' sillytavern

Or view the full container status including health:

docker ps

The STATUS column will show healthy, unhealthy, or starting alongside the uptime.

If you don't need the healthcheck feature, you can disable it by:

1. Setting the environment variable to 0:

   environment:
     - SILLYTAVERN_HEARTBEATINTERVAL=0

2. Removing or commenting out the healthcheck section in your docker-compose.yml.

Linux distributions with SELinux enabled (such as RHEL, CentOS, Fedora, etc.) may prevent Docker containers from accessing mounted volumes due to security policies. This can result in permission denied errors when the container tries to read or write to the mounted directories.

Two suffixes :z or :Z can be added to the volume mount. These suffixes tell Docker to relabel file objects on the shared volumes.

• The z option is used when the volume content will be shared between containers.
• The Z option is used when the volume content should only be used by the current container.

Example:

# docker-compose.yml
volumes:
  ## Shared volume
  - ./config:/home/node/app/config:z
  ## Private volume
  - ./data:/home/node/app/data:Z

1. Execute the following Docker command to obtain the IP of your SillyTavern Docker container.

   docker network inspect docker_default

   You should receive some sort of output similar to the following below.

   [
       {
           "Name": "docker_default",
           "IPAM": {
               "Config": [
                   {
                       "Subnet": "172.18.0.0/16",
                       "Gateway": "172.18.0.1"
                   }
               ]
           }
       }
   ]

   Copy down the IP you see in Gateway as this will be important.

2. Running a text editor of your choice with administrator rights, go to config and open config.yaml.

   Within your editor, go down to the whitelist section. You should see something similar to the following below.

   whitelist:
       - 127.0.0.1

   Add a new line below 127.0.0.1 and put in the IP you copied from Docker. It should look something similar to the following afterwards.

   whitelist:
       - 127.0.0.1
       - 172.18.0.1

   Save the file and exit the text editor.

   Note that if you configured Docker network as a bridge, you could also add external IP addresses to the whitelist as usual.

3. Restart the Docker Container to apply the new configuration.

   docker compose restart sillytavern