Platform: Setup & Run with Docker

Docker is the recommended method of running redball. The provided Docker image includes Python and all required modules.

Pre-Work

Create directories on your server where logs and database files will be stored, so the files will exist outside the Docker containers (otherwise they will be lost every time you stop the docker container). Also create a folder for custom templates and SSL certificate files, if you will be using those. For example let's say you created c:\users\yourusername\redball\data for database files, c:\users\yourusername\redball\logs for logs, c:\users\yourusername\redball\custom_templates for custom templates, and c:\users\yourusername\redball\certs for SSL certificate files. You'll want to mount these directories under /app, since that is the application root in the Docker container. Also don't forget to put /app/custom_templates in your BOT > TEMPLATE_PATH setting and /app/certs/<filename> in your System Config > Web/Security > Certificate* settings.

Run Using Docker Compose

Docker Compose saves your settings in a YAML file, which means you don't have to remember long commands each time you want to update your application. There is a docker-compose.yml file included in this repository, which you can adjust to meet your needs.

Mapped Volumes/Files

The provided docker-compose.yml file assumes you will keep your data, logs, custom_templates and certs folders in the same directory as docker-compose.yml. If this is not the case, replace ./data, ./logs, etc. with the applicable paths. If you will not be mapping one or more of these volumes, then remove the unnecessary line(s).

volumes:
  - ./data:/app/data
  - ./logs:/app/logs
  - ./custom_templates:/app/custom_templates
  - ./certs:/app/certs

Timezone

Update the TZ environment variable to your server timezone, if it's not America/New_York.

environment:
  - TZ=America/New_York

Port Mapping

You do not need to change the port redball listens on. If you want to use a port other than the default 8087, just change the host port on the Docker container to the one forwarded through your router/firewall, and keep 8087 for the container port. The host and container ports do not need to be the same. For example, if you want to use port 12345, update the ports section of docker-compose.yml to 12345:8087 instead of 8087:8087. If you do change the port in redball settings or you want to forward the SSL port instead, update the ports section of docker-compose.yml with the applicable host and container ports.

You also need to allow port 8087 (or selected port) through your firewall, if you want to allow access from the Internet.

Creating and Running the Container

• Make sure your current working directory is your redball folder (where docker-compose.yml is) and run the command docker-compose up -d to create and start a docker container based on the settings in docker-compose.yml.
  • Note: You will need to run all Docker commands as root or using sudo. On Windows you will need to run your command prompt as an admin.

Upgrading redball Using Docker Compose

To update your docker image to the latest version of Addarr, run the following commands:

• docker-compose pull (to pull the new version of the image from Docker Hub)
• docker-compose down (stop and destroy the current container--your config/data will be safe since you mapped them to persistent volumes)
• docker-compose up -d (create and start a new container)

Run Using Docker

Run the following command to pull the image from Docker Hub:

docker pull toddrob/redball:latest

Then create a container, including mapped paths for /app/logs, /app/data, and /app/custom_templates, as well as a TZ environment variable with your timezone name (e.g. America/New_York).

For Windows, replace \ with ` on the end of each line.

docker create \
  --name=redball \
  -v c:/users/yourusername/redball/data:/app/data \
  -v c:/users/yourusername/redball/logs:/app/logs \
  -v c:/users/yourusername/redball/custom_templates:/app/custom_templates \
  -v c:/users/yourusername/redball/certs:/app/certs\
  -e TZ=America/New_York \
  -p 8087:8087 \
  --restart unless-stopped \
  toddrob/redball:latest

Note: You do not need to change the port redball listens on. If you want to use a port other than the default 8087, just change the host port on the Docker container to the one forwarded through your router/firewall, and keep 8087 for the container port. The host and container ports do not need to be the same. For example, if you want to use port 12345, include -p 12345:8087 in the above command instead of -p 8087:8087. If you do change the port in redball settings or you want to forward the SSL port instead, update the docker command with the applicable host and container ports.

You also need to allow port 8087 (or selected port) through your firewall, if you want to allow access from the Internet.

Upgrading redball Using Docker

In order to upgrade redball to the latest version, you will need to stop and delete your existing docker container, pull the latest image from docker, create a new container using the new image, and start the new container. I recommend using a script similar to the following (based on the docker create command from above), so you can either run the script or copy/paste into your terminal/powershell (change \ to ` if using Windows):

docker stop redball
docker pull toddrob/redball:latest
docker container rm redball
docker create \
  --name=redball \
  -v c:/users/yourusername/redball/data:/app/data \
  -v c:/users/yourusername/redball/logs:/app/logs \
  -v c:/users/yourusername/redball/custom_templates:/app/custom_templates \
  -v c:/users/yourusername/redball/certs:/app/certs\
  -e TZ=America/New_York \
  -p 8087:8087 \
  --restart unless-stopped \
  toddrob/redball:latest
docker start redball

Latest, Beta, Alpha, and Specific Versions

A docker image for each version will be available, along with a number of static release tags that will always be available. Replace the tag in your docker create command with the release tag or specific version you want.

• toddrob/redball:latest - latest stable version, always available (once the first stable version is released)
• toddrob/redball:beta - latest beta version, always available (will point to toddrob/redball:latest if the latest beta version is older than the latest stable version)
• toddrob/redball:alpha - latest alpha version, always available (will point to toddrob/redball:latest if the latest alpha version is older than the latest stable version)
• toddrob/redball:<version> - specific version, e.g. toddrob/redball:v0.0.1-alpha for the v0.0.1-alpha version, toddrob/redball:v1.0.0 for the v1.0.0 major version (once that version is available)