HomeDock OS Configuration Guide

Instructions for configuring HomeDock OS, covering essential settings and explaining key configuration files.

Basic Configuration Overview

HomeDock OS requires specific dependencies and configuration files to ensure smooth operation. Below is a breakdown of the necessary Python dependencies, the main configuration files, and their settings.

Python Dependencies

Make sure the following Python3 libraries are installed to run HomeDock OS:

Core Libraries: Flask, Flask-Login, Flask-Limiter, Flask-Compress
Server Libraries: requests, Hypercorn, Zeroconf
Configuration and Utility Libraries: PyYAML, ConfigParser, psutil
Security Libraries: bcrypt, cryptography, Werkzeug
Other Utilities: colorama, Cython, docker

Main Configuration Files

`homedock_server.conf`

The main configuration file for HomeDock OS is homedock_server.conf. It contains settings related to the user account, server details, themes, and storage options.

Example configuration:

[Config]
user_name = Username
user_password = $2b$_bcrypt_hash_private_
run_port = 80
dynamic_dns = get.homedock.cloud
local_dns = True
run_on_development = False
disable_usage_data = False
delete_old_image_containers_after_update = False
delete_old_image_containers_after_uninstall = False
delete_internal_data_volumes = True
default_external_drive = /dev/sdXY
selected_theme = default
selected_back = back1.jpg

Key Configuration Options

user_name: The username for logging into HomeDock OS.
user_password: The bcrypt-hashed password for login security. Password updates are rehashed after updating the password.
run_port: The port on which HomeDock OS will operate. Ensure this port is open on your firewall/router.
local_dns: Set to True to enable homedock.local domain on your local network.
dynamic_dns: The dynamic DNS address to link with your instance (optional).
run_on_development: Set to True for development mode; otherwise, leave as False, will get deprecated over the time.
disable_usage_data: Set to True to disable the anonymous usage heartbeat (just a ping). _{Learn More}
delete_old_image_containers_after_update: Automatically deletes old container images after an update if set to True.
delete_old_image_containers_after_uninstall: Removes container images when they are uninstalled.
delete_internal_data_volumes: Remove all user and application data on persistent volumes. Use with caution, changes are permanent.
default_external_drive: Sets the external drive for storing files (e.g., /dev/sdb2).
selected_theme and selected_back: Controls the UI theme and background image for the interface.

Tip: While most of the modifications made in homedock_server.conf doesn’t require a restart of the HomeDock OS service to take effect, some of them like run_port or run_on_development may need it.

`homedock_ports.conf`

The homedock_ports.conf file manages port assignments for the applications running on HomeDock OS. This file is updated automatically when it detects a port change or through the frontend panel.

Example configuration:

wireguard*hostmode
filebrowser*8765
plex*32400
ddclient*hostmode
msedge*disabled
immich*17486
immich_postgres15*5432:5432
immich_redis*6379:6379

Each line follows the format: application_name*port_mode_or_number.

Port Modes

hostmode: Runs the application on the host network without specifying a port, ideal for services.
disabled: Means the application was installed once, then uninstalled or removed.
port_number: Assigns a specific port for the application, e.g., 32400 for plex.

Important Notes

Automatic Updates: Ports in homedock_ports.conf are updated automatically by the system or can be manually configured through the frontend once logged in.
Port Conflicts: Ensure that ports are not duplicated across applications to avoid conflicts.

`homedock_dropzone.conf`

The homedock_dropzone.conf file is crucial for managing the Drop Zone feature in HomeDock OS. This file contains encryption keys and settings that ensure secure file transfers and storage.

Example configuration:

!!!!! Do not delete or modify this file to prevent data corruption !!!!!
dz_key: 0rTTdhX2JyXBhAKUC6VwNyngtQWztIwn3sFUGieqdT0=
dz_key:user: rsuADwfTI/2OBvB9cyA6X/i7BZhaYsQZ5XuqGVggALw=
dzkey_v2:user:iGf86qCj4LKS5nEP/PjtXg==:fPkL4UQFUkT+8QXpgUHqc25NuIo9RTXwoe/zEHr8DWU=

The keys dz_key and dz_key:username are now deprecated in benefit of the new dzkey_v2. For more information about how secure Drop Zone is, please refer to the Drop Zone section.

Advanced Configuration

Explore additional ways to personalize and secure your HomeDock OS environment with advanced configuration options. Whether you’re managing SSL certificates for secure connections or customizing the visual theme to match your style, these settings provide greater control and flexibility.

SSL Configuration

HomeDock OS provides seamless SSL management to secure all applications and services with HTTPS.

For Cloud Instance users, SSL certificates are automatically issued and reissued upon hostname changes, requiring no manual setup. In contrast, Self-Hosted users need to configure a renewal hook to place updated certificates in the /DATA/SSLCerts directory, ensuring continuous HTTPS support.

For detailed steps and file structure requirements, please refer to the SSL Configuration guide.

Theme Customization

Modify the selected_theme and selected_back fields in homedock_server.conf or through the frontend once logged in to change the interface appearance. Themes can be customized to match organizational branding or personal preferences. Users can upload their own wallpapers for the Aero+ theme.

Summary

This configuration guide provides the essential settings and files needed to customize HomeDock OS. Whether you are using a Cloud Instance with automatic configurations or a Self-Hosted setup, these files allow you to manage user accounts, application ports, and system themes effectively.