Virtual Environment

Preferred method is docker but you can also run in a Python virtual environment located a .venv folder

• create the virtual environment:

python3 -m venv .venv

• activate the virtual environment (macOS/Linux):

source .venv/bin/activate

• set settings in settings.env
• run the script

 python3 octofree/octofree.py 

Unraid Server

• add CONTAINER
• repo url:

ghcr.io/dopeytree/octofree:latest 

• advanced --> icon url:

https://github.com/dopeytree/octofree/blob/61e16adea141812f674ca91d86ab697ac02e0c91/logo_octofree.png?raw=true

add VARIABLE -> discord:

• key =

DISCORD_WEBHOOK_URL

• value =
• enter_your_discord_server_webhook

add VARIABLE -> test mode:

• key=

TEST_MODE

• value =

false

add VARIABLE -> loop:

• key =

SINGLE_RUN

• value =

false

add PATH:

• container path =

  /data

• host path =

/mnt/user/appdata/octofree

APPLY settings

Docker

• Official published image on GitHub Container Registry :

docker pull ghcr.io/dopeytree/octofree:latest

Run the published image (recommended):

docker run --rm \
  --env-file ./octofree/settings.env \
  -v /path/on/host/octofree-data:/data \
  ghcr.io/dopeytree/octofree:latest

Notes:

• Use --env-file ./octofree/settings.env or set individual -e variables to provide your
  • DISCORD_WEBHOOK_URL, OUTPUT_DIR, and other options
  • If no settings.env file exists in your workspace, copy or create one from octofree/settings.env.template
• Bind-mount a host folder to persist logs and state
  • Set OUTPUT_DIR=/data (or another mounted path) so the output/ files appear on the host

Optional quick local build:

# Build locally (if you need to modify code or prefer a local image)
docker build -t octofree ./octofree

# Run the locally built image
docker run --rm --env-file ./octofree/settings.env -v /path/on/host/octofree-data:/data octofree

If you want the helper script and vulnerability scan, run the included ./octofree/build.sh (it builds the image and runs a Trivy scan).

Example docker-compose.yml (recommended for long-running deployments):

version: '3.8'
services:
  octofree:
    image: ghcr.io/dopeytree/octofree:latest
    environment:
      - DISCORD_WEBHOOK_URL=${DISCORD_WEBHOOK_URL}
      - OUTPUT_DIR=/data
      - SINGLE_RUN=false
      - TEST_MODE=false
    volumes:
      - /path/on/host/octofree-data:/data
    restart: unless-stopped

Docker Tips & troubleshooting

• If you change settings.env locally, avoid rebuilding by supplying --env-file or -e variables at docker run time
• Check logs and last-sent session inside the mounted folder (octofree.log, last_sent_session.txt) when debugging notifications
• The build.sh script runs Trivy; if you don't have Trivy available you can skip it and use docker build directly

Discord Webhook Notification

• [required for notifications]
• load or create a server in discord
• create a new channel called 'octofree'
• click the cogs to get the settings then find the webhooks button
• create a new webhook & copy the url
• set your discord webhook URL in settings.env

DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...

Test Mode

• allows multiple notifcation testing when 1x is live
• DEFAULT=false to send only 1x notification per saving sessions
• set to true to send > than 1x notification per current session
• true currently only works during an active saving session
• true sends time date, then 1min sends 5min delta, then end state
• true allows testing of discord on mobile etc

TEST_MODE=false
TEST_MODE=true

Single Run

• to loop or not
• true = runs the script once & exits (instead of looping every hour)
• DEFAULT=false
• set to false for continuous hourly monitoring

SINGLE_RUN=false
SINGLE_RUN=true

Storage

Only required for unraid & docker

volumes:
      - /path/on/host/octofree-data:/data