How HomelabOS uses Storage¶
Understanding storage types and their uses¶
There are 3 kinds of storage related to Docker and Docker compose. And by extension, HomelabOS.
Ephemeral - This storage disappears when the container is shut down. It's used for things like temp storage for a containers services.
Volume - These are mounted by the container and 'map' a physical (host, ubuntu) directory, to a containers internal directory. Volumes are used for persistent storage. For instance, Mysql's DB storage directories are mapped to host folders so that even if the container restarts, the db's storage exists when it restarts. You'll see these referenced in docker-compose.yml files like this:
volumes: - /var/homelabos/serviceName:/MyFiles
This mapping of a volume means that the container, and it's software can access the contents of
/var/homelabos/serviceName by accessing it's own
- NAS - Network Attached Storage volume(s) - NAS Volumes - are volumes, but they're controlled, in part, by HomelabOS. If you enable NAS storage in your config, and provide valid credentials to your NAS, HomelabOS will take care of mounting your NAS for you.
Understanding Collection Auto-Volumes¶
HomelabOS provides a number of services designed to act on, or share, collections of data. For instance, Airsonic is designed to provide you a web interface to your music collection. But Airsonic isn't alone. Jellyfin, Plex and Funkwhale all provide that same access to your music collection. To enable these services to share access to a common collection of media (or documents, etc.) HomelabOS understand, and maintains a series of collection folders that are auto-mapped by docker when the service is brought online. HomelabOS uses the following Collection Auto-volumes
In general, if it makes sense for a HomelabOS service to have access to a given collection, you'll find that it's automatically set up for you. For instance, out of the box, Airsonic has access to the Music volume, and Nextcloud has access to the Documents volume.
These folders are maintained by HomelabOS inside the directory specified by the
storage_dir configuration variable.
storage_dir config variable¶
Your settings/config.yml file contains a variable named
storage_dir that defaults to the directory
Despite the name, this folder does not have to be a NAS Mount.
If you're not using a NAS, because you've got an external hard drive attached, or an internal raid array you've already mounted that's fine. Just set the
storage_dir config variable to the directory where you have mounted your storage.
Whenever you enable a service, HomelabOS verifies that the storage_dir contains directories that match the collection auto-volumes mentioned above.
Setting up and mounting storage is a complex and potentially destructive task. It is outside the scope of this document to help you mount your storage on your Homelab server. Please research, and be careful.
At some point, you may need to change where your
storage_dir points, either because you've run out of space, or moved to a NAS. The following are high-level instructions on what you need to do to migrate your data from one storage asset to another.
systemctl stop dockeron your HomelabOS server to disable all HomelabOS services that might try to read or write to your existing storage directory
- Mount your new storage somewhere other than
- Copy or Move the contents of your
/mnt/nasdirectory to the newly mounted directory.
- Edit your.
storage_dirto point at the newly mounted directory.
systemctl start dockeron your HomelabOS server to reenable docker
hlos updateto re-deploy HomelabOS with the new storage_dir set.
Understanding NAS configuration for HomelabOS¶
HomelabOS has a NAS section in the
settings/config.yml file. This allows you to specify the connection details and credentials to accees your NAS. These details are used in conjunction with the
storage_dir variable to create and maintain
HomelabOS is configured to write
/etc/fstab entries that mount your NAS folders within, or on top of the
storage_dir directory Be careful not to mount your NAS folders over existing files in your
storage_dir or you'll be very confused.
Your NAS options are:
Truemeans that HomelabOS will start maintaining the mounting of your NAS for you, after you run hlos update
nas_host: this is the IP or hostname of your NAS server/device. ie: 192.168.1.130
nas_mount_type: your options here are
smb. While Ubuntu can mount just about anything, HomelabOS only knows how to maintain those three connection types.
nas_share_path: this represents the path to the shared directory on your NAS.
nas_user: username to authenticate with. *defaults to the value of
nas_pass: password to authenticate with.
nas_workgroup: Workgroup needed for some SMB/CIFS shares.