Skip to content
HomeDock OS

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:

homedock_server.conf
[Config]
user_name = Username
user_password = $2b$_bcrypt_hash_private_
run_port = 80
local_dns = true
dynamic_dns = your.domain.name
run_on_development = false
delete_old_image_containers_after_update = false
delete_old_image_containers_after_uninstall = false
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.
  • 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.
  • 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:

homedock_ports.conf
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.

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.