# Docker Installation

These instructions assume you have installed Docker, are able to access your command line for the installation of containers, and familiar with their general operation.

# Using the GitHub Container Registry

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.

# Docker Compose (recommended)

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.

# Docker CLI (advanced)

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:

# Container Variables

# Volume Mappings

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

# Port Mappings

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.

# Additional Settings

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.

# Running the container

Open your Command Line
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"

By default the container will run in the foreground. If you want to run it in the background, add the -d flag to the docker run command.

# Building the Docker Image

The following section assumes you installed SillyTavern in a non-root (non-admin) folder. If you installed SillyTavern in a root folder, you may have to run some of these commands with administrator rights [sudo, doas, Command Prompt (Administrator)].

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.

# Linux

Install Docker by following the Docker installation guide here.

Do not install Docker Desktop.
Follow the steps in Manage Docker as a non-root user in the Docker Post-Installation Guide.
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
```

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

Execute docker compose by running the following command within the Docker folder.
```
docker compose up -d
```
Open a new browser and go to http://localhost:8000. You should see SillyTavern load in a few moments.

# Windows

Regarding Docker on Windows

Using Docker on Windows is really complicated. Not only do you need to activate Windows Subsystem for Linux within Turn Windows features on or off, but also configure your system for Virtualization (Intel VT-d/AMD SVM) which differs from PC manufacturer to PC manufacturer (or motherboard manufacturer). Sometimes, this option is not present on some systems.

It is highly suggested you install SillyTavern by following our Windows guide. This section is a rough idea of how it can be done on Windows.

Install Docker Desktop by following the Docker installation guide here.
Install Git for Windows.

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

Execute docker compose by running the following command within the Docker folder.
```
docker compose up -d
```
Open a new browser and go to http://localhost:8000. You should see SillyTavern load in a few moments.

# macOS

Even though macOS is similar to Linux, it doesn't have the Docker Engine. You will have to install Docker Desktop similarly to Windows. You will also need to install Homebrew in order to install Git on your Mac. This section is a rough idea on how it can be done on macOS.

Install Docker Desktop by following the Docker installation guide here.
Install git using Homebrew.
```
brew install git
```

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

Execute docker compose by running the following command within the Docker folder.
```
docker compose up -d
```
Open a new browser and go to http://localhost:8000. You should see SillyTavern load in a few moments.

# Configuring SillyTavern

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.

Don't forget to restart the Docker container for SillyTavern in order to apply your changes! Make sure you execute this command within the docker folder.

docker compose restart sillytavern

# Locating User Data

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 Server Plugins

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.

Note

If you already see a plugins folder within the docker folder, you can skip Steps 1-2.

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"

Create a new folder within the docker folder called plugins.
Follow your plugin's instructions on installing the plugin.
Using nano or a code editor with administrator rights, open config.yaml (within the config folder) and enable enableServerPlugins
```
enableServerPlugins: true
```
Restart the Docker container.
```
docker compose restart sillytavern
```

# Common issues with Docker

# SELinux Permission Issues with Mounted Volumes

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

# Forbidden by Whitelist

Docker gateway IPs should be whitelisted automatically if whitelistDockerHosts config value is set to true.

If you are still unable to access SillyTavern, follow the instructions below to update the whitelist manually.

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.

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.
Restart the Docker Container to apply the new configuration.
```
docker compose restart sillytavern
```