Install¶
If you're migrating from Cloudbox you probably want the Cloudbox migration instructions
Warning
The Saltbox install is expecting a fresh new install of Ubuntu. DO NOT try to install it on your existing Cloudbox, PTS or other system-wide setup.
Please read through these steps prior to executing any of them, just to get a grounding in what is going to happen through out the process. It could be that things in later steps inform your decisions in earlier steps.
Broadly, the base install consists of six steps:
- Installing dependencies
- Preparing your configuration file(s)
- Running a pre-install script
- Configuring your cloud storage
- Running the install script
- Configuring installed applications
ALL STEPS ARE REQUIRED
Warning
There is no "uninstall" available. To uninstall Saltbox entirely, you will need to wipe the machine and reinstall the OS. You can remove all the containers, services, data, and the like, but there is no tracking of applications and packages that are installed in the OS.
However, it is safe to run any saltbox tag[s] [including the install tags] at will. Existing configurations are not overwritten [except for some "reset" tags and the "mounts" tag].
Step 1: Dependencies¶
Info
This is assuming you are logged into your freshly installed remote server as root
.
curl -sL https://install.saltbox.dev | sudo -H bash && cd /srv/git/saltbox
wget -qO- https://install.saltbox.dev | sudo -H bash && cd /srv/git/saltbox
curl -sL https://install.saltbox.dev | sudo -H bash -s -- -v && cd /srv/git/saltbox
wget -qO- https://install.saltbox.dev | sudo -H bash -s -- -v && cd /srv/git/saltbox
What will I see in the terminal?
Something like this:
~$ curl -sL https://install.saltbox.dev | sudo -H bash && cd /srv/git/saltbox
jammy is currently supported.
x86_64 is currently supported.
Installing Saltbox Dependencies.
/srv/git/saltbox$
Info
See here for more information about the dependencies.
Step 2: Configuration¶
Make sure you fill out the following configuration files before proceeding. Each file will be located in /srv/git/saltbox
Info
The following steps assumes you are still logged in as root or using sudo with the following commands.
To edit any of the following configuration files use the command written in the config title.
---
apprise: # (1)!
cloudflare:
email: # (2)!
api: # (3)!
dockerhub:
user: # (4)!
token: # (5)!
user:
name: seed # (6)!
pass: password123 # (7)!
domain: testsaltbox.ml # (8)!
email: your@email.com # (9)!
ssh_key: # (10)!
-
apprise url. See https://github.com/caronc/apprise#popular-notification-services for more information.
apprise: discord://webhook_id/webhook_token
-
Email used for the Cloudflare account.
-
Cloudflare Global API Key.
-
Docker Hub account name. Entering these credentials will at least double your image pull capacity from 100 every 6 hours to 200. https://www.docker.com/blog/checking-your-current-docker-pull-rate-limits-and-status/
-
Docker Hub account token. Not your password. A token can be created in the Security tab of your Docker Hub account.
-
Username that will be created (if it doesn't exist) during the installation and apps that have automatic user configuration.
Do not use root.
Required.
-
Password used for username account during the installation and apps that have automatic user configuration.
See the password considerations.
Required.
-
Domain that you want to use for the server.
Required.
-
Email address used for Let's Encrypt SSL certificates.
Required.
-
SSH Public Key. The key will be added to your configured user's
authorized_keys
file. This parameter accepts either the public key or a GitHub url (i.e. https://github.com/charlie.keys) which will pull the keys you have added to your GitHub account.
Note that you will likely not be able to fill in the rclone remote information until after you've completed the upcoming "Step 4: Rclone" This is fine and expected.
---
authelia:
master: yes # (1)!
subdomain: login # (2)!
downloads: /mnt/unionfs/downloads # (3)!
rclone:
enabled: yes # (4)!
remotes: # (5)!
- remote: google # (6)!
settings:
enable_refresh: yes # (18)!
mount: yes # (7)!
template: google # (8)!
union: yes # (9)!
upload: yes # (10)!
upload_from: /mnt/local/Media # (11)!
vfs_cache:
enabled: no # (12)!
max_age: 504h # (13)!
size: 50G # (14)!
- remote: dropbox
settings:
enable_refresh: yes
mount: yes
template: dropbox
union: yes
upload: no
upload_from: /mnt/local/Media
vfs_cache:
enabled: no
max_age: 504h
size: 50G
- remote: feeder
settings:
enable_refresh: yes
mount: yes
template: sftp
union: yes
upload: no
upload_from: /mnt/local/Media
vfs_cache:
enabled: no
max_age: 504h
size: 50G
version: latest # (15)!
shell: bash # (16)!
transcodes: /mnt/local/transcodes # (17)!
-
If the current server should have Authelia installed or use one installed elsewhere. For a multi-server setup, review the considerations listed for your Authelia setup.
-
Subdomain used for Authelia.
Use different values here when using a Mediabox + Feederbox setup if deploying multiple Authelia instances.
On a Feederbox where you want to use Authelia on the Mediabox just put in the same subdomain the Mediabox uses for Authelia (master having been set to no on the Feederbox). Review the considerations listed for your Authelia setup.
-
Folder used for docker /downloads volume. Does not affect mergerfs (/mnt/unionfs).
-
Toggle to enable/disable Rclone related deployments like mounts and cloudplow.
-
This variable takes a list of dictonaries formatted like the example.
Add as many remotes as you want.
-
The name of the Rclone remote you want to use.
You can also specify a path to use for the remote.
orremote: "google:Media"
remote: "my-sftp:/path/to/my/files"
-
Toggles whether you wqant this remote mounted into the file system.
-
The name of the template you want to use for the mount.
Currently Saltbox supports 4 options:
google
,dropbox
,sftp
and alternatively a path to a file ("/opt/mount-templates/custom/remote.j2") containing either jinja2 template or an actual copy of a systemd service file.We recommend having the template file in a folder in /opt so that it moves with your install after a restore.
-
Toggles whether you want this remote mount included in the union at
/mnt/unionfs
. This requires thatmount
be enabled. -
Toggles whether you intend to upload to this remote using Cloudplow.
-
Defines the local path Cloudplow will use to upload from if the remote was upload enabled.
-
Toggle for using Rclone VFS file cache.
-
Defines the max age of files in the cache.
-
Defines the max size of the cache.
The cache can grow above this value in actual usage (polls the cache once a minute) so leave some headroom when using this.
-
Rclone version that Saltbox will install.
Valid options are latest, beta or a specific version "1.55".
If specifying a version make sure to quote it as Ansible will convert the value into a float otherwise.
-
Shell used by the system. Valid options are bash or zsh.
-
Folder used for temporary transcode files.
-
Does this remote type require a refresh service to find new files? For example,
sftp
---
dns:
ipv4: yes # (1)!
ipv6: no # (2)!
proxied: no # (3)!
docker:
json_driver: no # (4)!
gpu:
intel: yes # (5)!
mounts:
ipv4_only: no # (6)!
system:
timezone: auto # (7)!
traefik:
cert:
http_validation: no # (8)!
zerossl: no # (9)!
error_pages: no # (10)!
hsts: no # (11)!
metrics: no # (12)!
provider: cloudflare # (13)!
subdomains:
dash: dash # (14)!
metrics: metrics # (15)!
-
Toggles Saltbox management of IPv4 A records with Cloudflare.
DNS management can be disabled on a per role basis with:
rolename_dns_enabled: false
Options are true or false
-
Toggles Saltbox management of IPv6 AAAA records with Cloudflare.
Additionally this toggle will enable Docker IPv6 networking when enabled.
DNS management can be disabled on a per role basis with:
rolename_dns_enabled: false
Options are true or false
-
Toggles the Cloudflare A or AAAA record proxy state (CDN) when records are changed.
This setting can be overridden on a per role basis using the inventory like this:
rolename_dns_proxy: false
Options are true or false
-
Changes the logging driver used by the Docker daemon from local to json-file.
More information can be found here
-
Toggles any tasks related to using Intel GPUs.
-
Toggles whether Rclone should be limited to IPv4 in case routing over IPv6 is bad to the destination of your configured remotes.
-
Configures the timezone used for the server and containers.
Default is
auto
which will attempt to pick the timezone based on Geolocation of the server.For entering a manual value you can find supported values by using:
Alternatively you can find a table on Wikipediatimedatectl list-timezones
-
Toggles whether Traefik is configured to use HTTP-01 certificate validation.
This toggle is only useful for those using any of the supported DNS validation methods as this will be enabled by default otherwise.
-
Toggles whether certificates will be issued by ZeroSSL instead of Let's Encrypt.
-
Toggles custom Traefik error pages.
See here for configuration details.
-
Toggles the use of HSTS.
-
Toggles the use of Traefik's Prometheus metrics endpoint, accessible at
https://metrics.domain.tld/prometheus
assuming default settings. -
Allows alternate DNS validation providers supported by Traefik.
Implemented ones are listed here.
-
Defines which subdomain the Traefik dashboard will be accessible at.
-
Defines which subdomain the Traefik Prometheus metrics endpoint will be accessible at.
Info
See here for more information about these settings.
Step 3: Preinstall¶
Warning
Make sure that you have set up the configuration correctly before proceeding.
This step will create the user account specified in accounts.yml
, add it to sudoers, update the kernel, edit GRUB configuration, install Rclone, and reboot the server if needed.
sb install preinstall
Warning
From this point you'll want to make sure you run commands as the user specified in the accounts.yml
If the server rebooted due to a kernel update, reconnect via SSH as the user specified in accounts.yml
.
If your server did not need to reboot, and the user in accounts.yml
is different from the user as whom you are currently connected to the server you can run su username
to switch user or disconnect and reconnect to SSH as the newly created user. Everything after this point will assume you are running as the user entered in accounts.yml
Info
If you are installing on a machine where you created a user as part of the ubuntu install, you are currently logged in as that user, and you entered that same user into accounts.yml
, you do not have to run su username
or reconnect to SSH as that user, and probably should not. You are already logged in as the "saltbox user", and you can just move on to the next step. The su username
or reconnect are typically required only on remote systems where you may be currently connected as root
.
Info
See here for more information about the preinstall.
Step 4: Rclone¶
Warning
As noted in the previous step, from this point you'll want to make sure you are logged into the server as the user specified in the accounts.yml
.
TO BE PERFECTLY CLEAR: FORGET THAT THE ROOT USER EXISTS. DO NOT LOG INTO YOUR SALTBOX MACHINE AS ROOT ANY MORE.
IF YOU THINK THIS DOESN'T APPLY TO YOU, THINK HARD ABOUT WHY YOU HAVE THAT IMPRESSION. ALMOST CERTAINLY YOU ARE MISTAKEN.
Info
THIS IS AN OPTIONAL STEP, required only if you plan to use cloud storage [Google Drive, for instance]
If you do not plan to use cloud storage, set the rclone -> enabled: false
setting in your settings.yml
, and skip this step.
If you already know how to set up an rclone remote pointing at cloud storage, do so with your usual methods. If not, here are five options.
Note that generally speaking these five options are mutually exclusive.
This option is aimed at you if you are migrating your cloudbox setup.
You already have the required setup complete. You should use your existing Google setup at least to start with.
Generally, migrating from Cloudbox to Saltbox involves restoring a Cloudbox backup. If you do not have a Cloudbox backup, but do have data on Google Drive from Cloudbox, go to the "Media on Google Drive" tab to the right.
This option is aimed at you if you are using some other setup with an rclone-based connection to cloud storage.
You probably already have the required setup complete. You should use your existing setup at least to start with.
You will need to enter details of your remote[s] into settings.yml
. If you have custom mount services, you can use them instead of one of the supplied templates. If not, perhaps start with the google
template to see if it's "good enough".
If you have lost your rclone config and need to recreate it, go to the "minimal setup" tab to the right. In step one, you can probably download the existing credential.
IF YOU ARE MIGRATING FROM ANY OTHER RCLONE-BASED SETUP THIS IS PROBABLY NOT WHAT YOU WANT.
The simplest possible case is:
- Set up a Google Project and OAuth Credential file if you don't already have one. This process is described here. You will need the ID and Secret from that process in step 3 below. That link takes you to one step in a multi-step process. Don't continue to follow that. Follow the steps on that page and then come back here.
- Create a Shared Drive in the Google Web UI. [optional] If you don't want to use a shared drive, skip this step, but know that some pieces of saltbox [notably drive monitoring in autoscan] won't work. This process is described here. If your Google account doesn't let you create shared drives, it's not the type af account we are assuming, and other things may not work as well.
- Create an rclone remote with those credentials. This process is described here.
- enter details about that remote in
settings.yml
Note: that mentions shared drives since that's our recommendation. If you want to point that remote at My Drive you can of course do so.
Note: This is the SIMPLEST POSSIBLE CASE as noted above; it doesn't discuss service accounts or multiple disks because it's the SIMPLEST POSSIBLE CASE.
- Create rclone remote[s] pointing at Dropbox as described here
- enter remote details in
settings.yml
Rclone supports a variety of cloud storage providers. This does not imply that any or all cloud storage providers are suitable for the saltbox use case.
You will need to perform two steps:
- Create an rclone remote pointing at your cloud storage as described here
- enter those remote details in
settings.yml
Once you have set up your rclone remote[s], enter their details in settings.yml
as discussed above in Step 2.
Warning
Do not proceed until you have fully configured your rclone remote[s] as described above or disabled cloud storage in the settings.
Step 5: Saltbox¶
Info
You must run at least core
prior to any other Saltbox tag; if you run any other tag prior to running core
, you will see a variety of odd errors. You need to run one of these options as shown below before moving on or installing any other tags/apps.
Warning
Have you either disabled rclone OR set up your remotes in both rclone config
and settings.yml
? If not, go back and fix that.
If you are installing a Feederbox/Mediabox setup [if your reaction to this question is "huh?" then you are not, and should probably use the saltbox
install], set up the Feederbox first, then add the feeder mount to the mediabox prior to install.
You can get a list of available install tags with sb list
.
saltbox
is an all-in-one media server for downloading and playback. It installs core
and a set of application as described here
sb install saltbox
mediabox
is just the parts required for playback. It installs core
and a set of application as described here
sb install mediabox
feederbox
is just the parts required for downloading. It installs core
and a set of application as described here
sb install feederbox
core
is the bare minimum required for saltbox. It installs the basics as described here
sb install core
If you want to install a personal selection of apps, install core
and the app tags you want as listed here
sb install core,plex,sonarr,radarr,jackett,qbittorrent
Info
See here for more information about the install.
Reboot¶
After rebooting, you're now ready to go through the basic setup for the apps!
Step 6: App Setup¶
If you would like to configure cloudplow to use service accounts to exceed Google's 750G daily upload limit, and you went through the scripted rclone setup above, you can do this now. Instructions are here.
Go through these one at a time in order; some of the setups depend on previous setups.
Info
This list is what's installed if you've run the saltbox
tag. If you ran core
, none of these are installed; if you ran feederbox
or mediabox
you have a subset of these.
- SABnzbd
- qBittorrent
- NZBHydra2
- Jackett
- Plex Media Server
- Autoscan
- Sonarr
- Radarr
- Lidarr
- Tautulli
- Overseerr
- Portainer
- Organizr
Info
These are not all the available applications, just the core set that are installed by the saltbox
tag. Click on the "Apps" header at the top for a full listing of applications available in Saltbox. Click the "Sandbox" heading for a listing of commmunity-supplied applications.
Next, some tasks to perform after installation is complete.