Lungo

A home lab setup for small-to-mid-scale private on-premises deployments,
with everything configurable in human-readable YAML files.

Features

• Fully configurable via YAML files - everything including user management
• Easy interoperability - single sign-on portal to access all applications
• Batteries-included - comes with a variety of applications out of the box
• Secure by default - is designed to be run in a non-root user environment

Installation

The easiest way to install Lungo is via pip:

pip install lungo-cli

To install from source, run:

git clone --recurse-submodules https://github.com/raymond-u/lungo
cd lungo
poetry install --compile

Getting started

Prerequisites

Lungo is built upon Docker and Docker Compose. Please ensure they are installed on your machine.

Alternatively, you can use Podman and Podman Compose.

For installation instructions, please refer to their respective documentation.

Rootless execution

For enhanced security, Lungo should be run in a non-root user environment. To do so, the administrator must complete necessary configurations, as described in the Docker guide or the Podman guide.

To enable non-root users to bind to port 80, run:

sudo setcap 'cap_net_bind_service=+ep' "$(command -v lungo)"

Or you can modify the value of net.ipv4.ip_unprivileged_port_start using the following command:

# This will allow any user to bind to port 80
sudo sysctl net.ipv4.ip_unprivileged_port_start=80

In a rootless environment, permissions need to be configured to allow non-root users on the host machine to read and write files created by the container, and vice versa. We recommend creating a dedicated user for Lungo and a group for sharing files between the container and the host. The following commands illustrate this process:

# Create a group for sharing files
sudo groupadd shared

# Create a dedicated user for Lungo
sudo useradd -m -g shared lungo

# Add an existing user to the group
sudo usermod -a -G shared <username>

# Create a directory for shared files
sudo mkdir /mnt/data/shared
sudo chown lungo:shared /mnt/data/shared
sudo chmod g+rws /mnt/data/shared

You can read more about file permissions in a rootless environment here.

Avoid using sudo su lungo to switch to the lungo user when launching Lungo in a rootless environment, as it may not function properly. Instead, set a password for the lungo user and log in normally:

sudo chpasswd <<<'lungo:<password>'

Configuration

Lungo has two essential configuration files: config.yaml and users.yaml. The config.yaml file contains general settings for Lungo, while the users.yaml file is dedicated to user management. The default location for these files is platform-dependent, i.e. ~/.config/lungo/ on Linux. You can override this location by passing the --config-dir option to Lungo.

For a full list of available settings, please refer to config.yaml and users.yaml. Also, you may find these examples helpful.

You can verify the correctness of your configuration files by running:

lungo check

Usage

To launch Lungo, just run:

lungo up

Additional notes

You might need to configure your firewall to permit access on ports 80 and 443. For instance, if you're using UFW, run:

sudo ufw allow http
sudo ufw allow https

License

This project is licensed under the MIT License. See LICENSE for details.