Lungo is a user-friendly home lab setup designed for small-to-mid-scale on-premises hosting.
"},{"location":"#features","title":"Features","text":"We believe that self-hosting should be accessible and straightforward for everyone, especially for small-to-mid-scale home lab setups where scalability and high availability may not be the primary concerns. Our focus is on prioritizing easy setup and low maintenance.
Lungo is specifically designed to meet these needs. It uses a YAML-based configuration system to simplify the customization of users, applications, and more. This eliminates the complexities associated with database maintenance and accelerates backup and restoration processes.
Lungo comes with a single sign-on portal and a diverse range of applications that can be individually enabled or disabled. You have the flexibility to grant application access on a per-role or per-user basis. Anonymous access is also supported when enabled.
Lungo not only works, but it also looks and feels great. It utilizes a modern UI framework and is designed to be responsive, ensuring a visually appealing and smooth user experience.
Lastly, Lungo prioritizes security by default. It comes with HTTPS and secure server settings out of the box, ensuring a secure environment, and can be configured to rate limit sensitive API endpoints.
"},{"location":"changelog/","title":"Changelog","text":""},{"location":"changelog/#nightly","title":"Nightly","text":""},{"location":"changelog/#changed","title":"Changed","text":"Host headerToo Many Requests errors in the web UIUpgrade headerinput element in the web UIInitial release
"},{"location":"cli-reference/","title":"lungo","text":"A CLI tool for Lungo: a user-friendly home lab setup designed for small-to-mid-scale on-premises hosting.
Usage:
lungo [OPTIONS] COMMAND [ARGS]...\nOptions:
-v, --version Show the version of the program and exit.\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or\n customize the installation.\nCheck if the configuration is valid.
Usage:
lungo check [OPTIONS]\nOptions:
-c, --config-dir PATH Path to the configuration directory.\n -q, --quiet Suppress all output except for errors.\n -v, --verbose Increase verbosity.\nStop the service.
Usage:
lungo down [OPTIONS]\nOptions:
--container-tool [docker|docker-compose|podman-compose]\n Container management tool to use.\n -c, --config-dir PATH Path to the configuration directory.\n --dev Use the development configuration.\n -q, --quiet Suppress all output except for errors.\n -v, --verbose Increase verbosity.\nStart the service.
Usage:
lungo up [OPTIONS]\nOptions:
--build-only Only build the container.\n --container-tool [docker|docker-compose|podman-compose]\n Container management tool to use.\n -c, --config-dir PATH Path to the configuration directory.\n --dev Use the development configuration.\n --force-init Do a fresh initialization.\n --remove-lock Remove the lock file.\n -q, --quiet Suppress all output except for errors.\n -v, --verbose Increase verbosity.\nLungo is built upon Docker Compose. Before proceeding, please ensure that Docker is installed on your machine.
Alternatively, you can use Podman Compose with Podman. You can also use Docker Compose with Podman.
For instructions on setting up these tools, please refer to their respective documentation.
"},{"location":"installation/#with-pipx","title":"With pipx","text":"The recommended way to install Lungo is with pipx:
Terminalpipx install lungo-cli\nTo install Lungo with pip, run:
Terminalpip install lungo-cli\nTo install Lungo from source, run:
Terminalgit clone --recurse-submodules https://github.com/raymond-u/lungo\ncd lungo\npip install .\n~/.config/lungo/config.yaml macOS ~/Library/Application Support/lungo/config.yaml Windows %USERPROFILE%\\AppData\\Local\\lungo\\lungo\\config.yaml config.yaml## Configuration file for general settings\n\n# =========\n# branding:\n# =========\n\n# # Custom name for the Lungo instance\n# # Type: string\n# # Default: 'Lungo'\n# # Required: no\n# name: Lungo\n\n# # Custom subtitle for the landing page\n# # Type: array\n# # Default: [ 'a hug in a mug', 'a poetry of aroma', 'a quiet solitude', 'a whisper of inspiration' ]\n# # Required: no\n# subtitle:\n# - a hug in a mug\n\n# # Custom cover image for the landing page\n# # Type: path\n# # Default: none\n# # Required: no\n# cover: /assets/cover.png\n\n# # Custom logo for the website\n# # Type: path\n# # Default: none\n# # Required: no\n# logo: /assets/favicon.png\n\n# ============\n# directories:\n# ============\n\n# # Cache directory\n# # Type: path\n# # Default: (platform specific)\n# # Required: no\n# cache_dir: ~/.cache/lungo\n\n# # Data directory\n# # Type: path\n# # Default: (platform specific)\n# # Required: no\n# data_dir: ~/.local/share/lungo\n\n# # Directory to store user data (e.g. user joe will have its data stored in joe/ inside this directory)\n# # Type: path\n# # Default: none\n# # Required: yes\n# users_dir: /home\n\n# # Directories to mount that are shared between the container and the host\n# shared_dirs:\n# -\n\n# # Name of the directory after mounted (must be unique)\n# Type: string\n# Default: none\n# Required: yes\n# name: shared_readonly\n\n# # Path to the directory on the host\n# # Type: path\n# # Default: none\n# # Required: yes\n# source: /mnt/data/shared_readonly\n\n# # Whether to mount the directory as read-only or not\n# # Type: boolean\n# # Default: false\n# # Required: no\n# read_only: true\n\n# ========\n# modules:\n# ========\n\n# # Settings for the File Browser module\n# filebrowser:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Settings for the JupyterHub module\n# jupyterhub:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Password for users inside the container\n# # Type: string\n# # Default: (randomly generated)\n# # Required: no\n# password: passwd\n\n# # Settings for the PrivateBin module\n# privatebin:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Settings for the RStudio module\n# rstudio:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Password for users inside the container\n# # Type: string\n# # Default: (randomly generated)\n# # Required: no\n# password: passwd\n\n# # Settings for the Xray module\n# xray:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Domain whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# domain_whitelist: [ ]\n\n# # Domain keyword whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# domain_keyword_whitelist: [ ]\n\n# # Domain suffix whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# domain_suffix_whitelist: [ ]\n\n# # IP range whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# ip_range_whitelist: [ ]\n\n# ========\n# network:\n# ========\n\n# # Hostname of the website\n# # Type: string\n# # Default: none\n# # Required: yes\n# hostname: lungo.com\n\n# # Subnet to use for the internal network, in CIDR notation (must have a minimum of 256 addresses)\n# # Type: string\n# # Default: 192.168.2.0/24\n# # Required: no\n# subnet: 192.168.2.0/24\n\n# # Trusted proxies (external IP addresses that are trusted to set the client IP address)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# trusted_proxies: [ ]\n\n# # HTTP settings\n# http:\n\n# # Enable or disable HTTP\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Port to use for HTTP\n# # Type: integer\n# # Default: 80\n# # Required: no\n# port: 80\n\n# # HTTPS settings\n# https:\n\n# # Port to use for HTTPS\n# # Type: integer\n# # Default: 443\n# # Required: no\n# port: 443\n\n# # Set custom TLS certificate and key\n# tls:\n\n# # Path to the TLS certificate\n# # Type: path\n# # Default: none\n# # Required: no\n# cert: /etc/ssl/certs/self-signed.crt\n\n# # Path to the TLS private key\n# # Type: path\n# # Default: none\n# # Required: no\n# key: /etc/ssl/private/self-signed.key\n\n# ======\n# rules:\n# ======\n\n# # Privileges of each role (privileges are inherited from roles above)\n# privileges:\n\n# # For unregistered users\n# unregistered:\n\n# # Allowed apps, or 'all' to allow all apps (do not allow services that require authentication)\n# # Type: 'all' | array\n# # Default: [ ]\n# # Required: no\n# allowed_apps: [ ]\n\n# # For guest users\n# guest:\n\n# # Allowed apps, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: ['filebrowser', 'privatebin']\n# # Required: no\n# allowed_apps:\n# - filebrowser\n\n# # For regular users\n# user:\n\n# # Allowed apps, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: ['jupyterhub', 'rstudio']\n# # Required: no\n# allowed_apps:\n# - rstudio\n\n# # For administrators\n# admin:\n\n# # Allowed apps, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: 'all'\n# # Required: no\n# allowed_apps: all\n\n# =========\n# security:\n# =========\n\n# # Rate limiting settings\n# rate_limiting:\n\n# # Enable or disable rate limiting\n# # Type: boolean\n# # Default: false\n# # Required: no\n# enabled: false\n\n# # Maximum number of requests in the given time window\n# # Type: int\n# # Default: 5\n# # Required: no\n# max_requests: 5\n\n# # Time window (in seconds, or a string describing a time span in ISO 8601 format)\n# # Type: int | string\n# # Default: 'PT1H'\n# # Required: no\n# time_window: 'PT1H'\n\n# # Session settings\n# session:\n\n# # Session lifetime (in seconds, or a string describing a time span in ISO 8601 format)\n# # Type: int | string\n# # Default: 'P1DT'\n# # Required: no\n# lifetime: 'P1DT'\n\n# =====\n# smtp:\n# =====\n\n# # SMTP server host\n# # Type: string\n# # Default: none\n# # Required: yes\n# host: smtp.gmail.com\n\n# # SMTP server port\n# # Type: integer\n# # Default: none\n# # Required: yes\n# port: 587\n\n# # SMTP server username\n# # Type: string\n# # Default: none\n# # Required: yes\n# username: joe\n\n# # SMTP server password\n# # Type: string\n# # Default: none\n# # Required: yes\n# password: joe123\n\n# # Sender name\n# # Type: string\n# # Default: 'Lungo'\n# # Required: no\n# name: Lungo\n\n# # Sender email\n# # Type: string\n# # Default: none\n# # Required: yes\n# sender: joe@gmail.com\n~/.config/lungo/users.yaml macOS ~/Library/Application Support/lungo/users.yaml Windows %USERPROFILE%\\AppData\\Local\\lungo\\lungo\\users.yaml users.yaml## Configuration file for user management\n\n# =========\n# accounts:\n# =========\n\n# # List of accounts\n# -\n\n# # Enable or disable the account\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: false\n\n# # Username\n# # Type: string\n# # Default: none\n# # Required: yes\n# username: joe\n\n# # Full name (first and last)\n# name:\n\n# # First name\n# # Type: string\n# # Default: none\n# # Required: yes\n# first: Joe\n\n# # Last name\n# # Type: string\n# # Default: none\n# # Required: yes\n# last: Doe\n\n# # Email address\n# # Type: string\n# # Default: none\n# # Required: yes\n# email: joe@gmail.com\n\n# # User role\n# # Type: 'guest' | 'user' | 'admin'\n# # Default: none\n# # Required: yes\n# role: user\n\n# # Extra configuration\n# extra:\n\n# # Allowed apps besides those defined in the role, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: [ ]\n# # Required: no\n# allowed_apps:\n# - rstudio\n\n# # Override user directory\n# # Type: path\n# # Default: none\n# # Required: no\n# user_dir: /mnt/somewhere/someone\n\n# # User-specific shared directories\n# shared_dirs:\n# -\n\n# # Name of the directory after mounted (must be unique)\n# Type: string\n# Default: none\n# Required: yes\n# name: shared_readonly\n\n# # Path to the directory on the host\n# # Type: path\n# # Default: none\n# # Required: yes\n# source: /mnt/data/shared_readonly\n\n# # Whether to mount the directory as read-only or not\n# # Type: boolean\n# # Default: false\n# # Required: no\n# read_only: true\nLungo utilizes two configuration files: config.yaml, which contains general settings, and users.yaml, dedicated to user management. By default, these files are located in a platform-dependent directory, such as ~/.config/lungo/ on Linux. You can override this location by passing the --config-dir option to Lungo.
A minimal config.yaml file looks like this:
directories:\n users_dir: /home/lungo/users\n\nnetwork:\n hostname: lungo.com\n\nsmtp:\n host: smtp.gmail.com\n port: 587\n username: joe\n password: joe123\n name: Lungo\n sender: joe@gmail.com\nFor a comprehensive list of available settings, please refer to the reference for config.yaml and reference for users.yaml.
"},{"location":"getting-started/configuring-settings/#verifying-settings","title":"Verifying settings","text":"You can verify the correctness of your configuration files by running:
Terminallungo check\nAfter making any changes to the config.yaml file, you need to restart the Lungo service for the changes to take effect.
To launch Lungo, simply run the following command:
Terminallungo up\nThis will start the Lungo service as a daemon.
"},{"location":"getting-started/managing-users/","title":"Managing users","text":""},{"location":"getting-started/managing-users/#adding-a-user","title":"Adding a user","text":"To add a new user, add an entry to the users.yaml file. Here is an example of a minimal entry:
accounts:\n - username: joe\n name:\n first: Joe\n last: Doe\n email: joe@gmail.com\n role: user\nThe username and email must be unique across all users. Note that you don't need to specify a password for the user. Instead, the user will use the password reset feature to set their own password.
A user can be assigned one of the following roles:
guestuseradminEach role inherits the permissions of the previous one. For example, a user with the admin role can perform all actions that a guest or user can.
extra.user_dir field","text":"Every user has a dedicated directory for storing their files. By default, this directory is located within users_dir. However, you can set the extra.user_dir field to specify a different location for a specific user. For instance:
accounts:\n - username: joe\n - username: jane\n extra:\n user_dir: /mnt/data/jane\nSuppose you have set users_dir to /home/lungo/users in your config.yaml file. In this case, the user joe will have /home/lungo/users/joe as their user directory, while the user jane will have /mnt/data/jane as their user directory.
To remove a user, simply remove the corresponding entry from the users.yaml file. Alternatively, you can set the enabled flag to false to disable the user without removing the entry.
After making any changes to the users.yaml file, you need to restart the Lungo service for the changes to take effect.
To ensure enhanced security, it is recommended to run Lungo in a non-root user environment. To achieve this, the administrator needs to perform specific configurations as outlined in the Docker guide or the Podman guide.
To allow non-root users to bind to ports below 1024, you can utilize the setcap command:
sudo setcap 'cap_net_bind_service=+ep' \"$(command -v lungo)\"\nAlternatively, 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\nsudo sysctl net.ipv4.ip_unprivileged_port_start=80\nIn a rootless environment, proper file permissions must be set to enable non-root users on the host machine to read and write files created from within the container, and vice versa. It is recommended to create a dedicated user for Lungo and a group for sharing files between the container and the host. The following commands demonstrate this process:
Terminal# Create a group for sharing files\nsudo groupadd shared\n\n# Create a dedicated user for Lungo\nsudo useradd -m -g shared lungo\n\n# Add an existing user to the group\nsudo usermod -a -G shared <username>\n\n# Create a directory for shared files\nsudo mkdir /mnt/data/shared\nsudo chown lungo:shared /mnt/data/shared\nsudo chmod g+rws /mnt/data/shared\nFor more information on file permissions in a rootless environment, you can refer to the documentation.
Avoid using sudo su lungo to switch to the lungo user when launching Lungo in a rootless environment, as it may lead to improper functioning. Instead, set a password for the lungo user and log in normally:
sudo chpasswd <<<'lungo:<password>'\nDepending on your firewall configuration, you might need to allow access to ports 80 and 443, or any other ports that you intend to use for HTTP and HTTPS. If you are using UFW (Uncomplicated Firewall), you can use the following commands:
Terminalsudo ufw allow http\nsudo ufw allow https\nPlease make sure to adjust the firewall settings according to your specific needs and security requirements.
"},{"location":"guides/allowing-anonymous-access/","title":"Allowing anonymous access","text":"In addition to the three roles (guest, user, and admin) that can be assigned to a user, Lungo also supports anonymous access, which is associated with the role unregistered. To enable anonymous access, you need to configure the unregistered.allowed_apps field in the config.yaml file:
rules:\n privileges:\n unregistered:\n allowed_apps:\n - privatebin\n - rstudio\nTo enable anonymous access for applications that typically require user accounts, such as RStudio, you must add a user with the username anonymous in the users.yaml file:
accounts:\n - username: anonymous\n name:\n first: Anonymous\n last: User\n email: an@nymo.us\n role: guest\nThe user with the username anonymous serves as a shared account for anonymous access. The name and email fields can be set to arbitrary values (although they must still be provided). The role field must be set to guest and cannot be changed.
To limit the number of requests made by each IP address to sensitive API endpoints within a specified time window, you can enable security.rate_limiting in the configuration file. This feature is particularly useful in safeguarding against brute-force attacks targeting authentication API endpoints.
For rootless containers, it is essential to configure both the network stack and the port forwarder to use slirp4netns in order to determine the actual client IP address. Before proceeding, ensure that slirp4netns is installed on your machine.
By default, Docker and Podman employ RootlessKit as the port forwarder. For Docker, you can find instructions on changing the port forwarder here. For Podman, you don't need to do anything, as slirp4netns can be picked up automatically.
Please note that it is crucial to correctly configure the container to use slirp4netns as mentioned above before enabling security.rate_limiting. Failure to do so will result in rate limiting being applied to all requests, irrespective of the IP address, as the container won't be able to determine the actual client IP address.
Moreover, when external proxies or load balancers are present in front of the container, it is necessary to specify their IP addresses in network.trusted_proxies in order to obtain the actual client IP address.
In the config.yaml file, you can find the users_dir field, which determines the storage location for user files. By configuring this setting, you can map the home directories of local users to the corresponding location inside the container.
directories:\n users_dir: /home\nTo enable write access to directories owned by a local user from within the container, you must ensure that the UID or GID of those directories matches the user running Lungo, and that appropriate write permissions have been granted.
For instance, consider a scenario where a directory is owned by the user joe, and Lungo is running with the user lungo. In this case, the directory should be assigned to the same group as the primary group of lungo, and group write permission should be granted. For more information, please refer to the file permissions section.
graph LR\n Host(Host) --> Portal(Portal<br /><br />Openresty)\n Portal -->|Perform real IP forwarding<br />and rate limiting| Proxy(Reverse Proxy<br /><br />Openresty)\n Proxy <--->|Authorize requests| Auth(Access Control<br /><br />Oathkeeper) ---> Control\n Proxy ---> UI(Web UI<br /><br />Node.js)\n UI --->|Find accessible apps| Control\n UI ---> Backends\n\n subgraph Control [ ]\n subgraph P1 [Access Control Backends]\n subgraph P2 [ ]\n direction TB\n Authenticator(Authenticator<br /><br />Kratos) ~~~ Authorizer(Authorizer<br /><br />Keto)\n end\n end\n end\n\n subgraph Backends [ ]\n subgraph P3 [App Backends]\n subgraph P4 [ ]\n direction TB\n App1(App 1) ~~~ App2(App 2) ~~~ App0(...)\n end\n end\n end\n\n classDef Dotted stroke-dasharray: 5 5\n class Control,Backends Dotted\n classDef Padding fill: none, stroke: none\n class P1,P2,P3,P4 PaddingLungo consists of three primary components:
Lungo prioritizes security and employs various measures to minimize the attack surface. The following outlines implemented security measures:
SameSite attribute is set to Lax.Path attribute.filebrowser JupyterHub jupyterhub PrivateBin privatebin RStudio rstudio Xray xray Legend:
Icon Meaning Fully supported Partially supported Planned"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Lungo","text":"Lungo is a user-friendly home lab setup designed for small-to-mid-scale on-premises hosting.
"},{"location":"#features","title":"Features","text":"We believe that self-hosting should be accessible and straightforward for everyone, especially for small-to-mid-scale home lab setups where scalability and high availability may not be the primary concerns. Our focus is on prioritizing easy setup and low maintenance.
Lungo is specifically designed to meet these needs. It uses a YAML-based configuration system to simplify the customization of users, applications, and more. This eliminates the complexities associated with database maintenance and accelerates backup and restoration processes.
Lungo comes with a single sign-on portal and a diverse range of applications that can be individually enabled or disabled. You have the flexibility to grant application access on a per-role or per-user basis. Anonymous access is also supported when enabled.
Lungo not only works, but it also looks and feels great. It utilizes a modern UI framework and is designed to be responsive, ensuring a visually appealing and smooth user experience.
Lastly, Lungo prioritizes security by default. It comes with HTTPS and secure server settings out of the box, ensuring a secure environment, and can be configured to rate limit sensitive API endpoints.
"},{"location":"changelog/","title":"Changelog","text":""},{"location":"changelog/#nightly","title":"Nightly","text":""},{"location":"changelog/#023-2024-2-16","title":"0.2.3 - 2024-2-16","text":""},{"location":"changelog/#changed","title":"Changed","text":"Host headerToo Many Requests errors in the web UIUpgrade headerinput element in the web UIInitial release
"},{"location":"cli-reference/","title":"lungo","text":"A CLI tool for Lungo: a user-friendly home lab setup designed for small-to-mid-scale on-premises hosting.
Usage:
lungo [OPTIONS] COMMAND [ARGS]...\nOptions:
-v, --version Show the version of the program and exit.\n --install-completion Install completion for the current shell.\n --show-completion Show completion for the current shell, to copy it or\n customize the installation.\nCheck if the configuration is valid.
Usage:
lungo check [OPTIONS]\nOptions:
-c, --config-dir PATH Path to the configuration directory.\n -q, --quiet Suppress all output except for errors.\n -v, --verbose Increase verbosity.\nStop the service.
Usage:
lungo down [OPTIONS]\nOptions:
--container-tool [docker|docker-compose|podman-compose]\n Container management tool to use.\n -c, --config-dir PATH Path to the configuration directory.\n --dev Use the development configuration.\n -q, --quiet Suppress all output except for errors.\n -v, --verbose Increase verbosity.\nStart the service.
Usage:
lungo up [OPTIONS]\nOptions:
--build-only Only build the container.\n --container-tool [docker|docker-compose|podman-compose]\n Container management tool to use.\n -c, --config-dir PATH Path to the configuration directory.\n --dev Use the development configuration.\n --force-init Do a fresh initialization.\n --remove-lock Remove the lock file.\n -q, --quiet Suppress all output except for errors.\n -v, --verbose Increase verbosity.\nLungo is built upon Docker Compose. Before proceeding, please ensure that Docker is installed on your machine.
Alternatively, you can use Podman Compose with Podman. You can also use Docker Compose with Podman.
For instructions on setting up these tools, please refer to their respective documentation.
"},{"location":"installation/#with-pipx","title":"With pipx","text":"The recommended way to install Lungo is with pipx:
Terminalpipx install lungo-cli\nTo install Lungo with pip, run:
Terminalpip install lungo-cli\nTo install Lungo from source, run:
Terminalgit clone --recurse-submodules https://github.com/raymond-u/lungo\ncd lungo\npip install .\n~/.config/lungo/config.yaml macOS ~/Library/Application Support/lungo/config.yaml Windows %USERPROFILE%\\AppData\\Local\\lungo\\lungo\\config.yaml config.yaml## Configuration file for general settings\n\n# =========\n# branding:\n# =========\n\n# # Custom name for the Lungo instance\n# # Type: string\n# # Default: 'Lungo'\n# # Required: no\n# name: Lungo\n\n# # Custom subtitle for the landing page\n# # Type: array\n# # Default: [ 'a hug in a mug', 'a poetry of aroma', 'a quiet solitude', 'a whisper of inspiration' ]\n# # Required: no\n# subtitle:\n# - a hug in a mug\n\n# # Custom cover image for the landing page\n# # Type: path\n# # Default: none\n# # Required: no\n# cover: /assets/cover.png\n\n# # Custom logo for the website\n# # Type: path\n# # Default: none\n# # Required: no\n# logo: /assets/favicon.png\n\n# ============\n# directories:\n# ============\n\n# # Cache directory\n# # Type: path\n# # Default: (platform specific)\n# # Required: no\n# cache_dir: ~/.cache/lungo\n\n# # Data directory\n# # Type: path\n# # Default: (platform specific)\n# # Required: no\n# data_dir: ~/.local/share/lungo\n\n# # Directory to store user data (e.g. user joe will have its data stored in joe/ inside this directory)\n# # Type: path\n# # Default: none\n# # Required: yes\n# users_dir: /home\n\n# # Directories to mount that are shared between the container and the host\n# shared_dirs:\n# -\n\n# # Name of the directory after mounted (must be unique)\n# Type: string\n# Default: none\n# Required: yes\n# name: shared_readonly\n\n# # Path to the directory on the host\n# # Type: path\n# # Default: none\n# # Required: yes\n# source: /mnt/data/shared_readonly\n\n# # Whether to mount the directory as read-only or not\n# # Type: boolean\n# # Default: false\n# # Required: no\n# read_only: true\n\n# ========\n# modules:\n# ========\n\n# # Settings for the File Browser module\n# filebrowser:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Settings for the JupyterHub module\n# jupyterhub:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Password for users inside the container\n# # Type: string\n# # Default: (randomly generated)\n# # Required: no\n# password: passwd\n\n# # Settings for the PrivateBin module\n# privatebin:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Settings for the RStudio module\n# rstudio:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Password for users inside the container\n# # Type: string\n# # Default: (randomly generated)\n# # Required: no\n# password: passwd\n\n# # Settings for the Xray module\n# xray:\n\n# # Enable or disable the module\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Domain whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# domain_whitelist: [ ]\n\n# # Domain keyword whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# domain_keyword_whitelist: [ ]\n\n# # Domain suffix whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# domain_suffix_whitelist: [ ]\n\n# # IP range whitelist (used only as a template for configuring the proxy client)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# ip_range_whitelist: [ ]\n\n# ========\n# network:\n# ========\n\n# # Hostname of the website\n# # Type: string\n# # Default: none\n# # Required: yes\n# hostname: lungo.com\n\n# # Subnet to use for the internal network, in CIDR notation (must have a minimum of 256 addresses)\n# # Type: string\n# # Default: 192.168.2.0/24\n# # Required: no\n# subnet: 192.168.2.0/24\n\n# # Trusted proxies (external IP addresses that are trusted to set the client IP address)\n# # Type: array\n# # Default: [ ]\n# # Required: no\n# trusted_proxies: [ ]\n\n# # HTTP settings\n# http:\n\n# # Enable or disable HTTP\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: true\n\n# # Port to use for HTTP\n# # Type: integer\n# # Default: 80\n# # Required: no\n# port: 80\n\n# # HTTPS settings\n# https:\n\n# # Port to use for HTTPS\n# # Type: integer\n# # Default: 443\n# # Required: no\n# port: 443\n\n# # Set custom TLS certificate and key\n# tls:\n\n# # Path to the TLS certificate\n# # Type: path\n# # Default: none\n# # Required: no\n# cert: /etc/ssl/certs/self-signed.crt\n\n# # Path to the TLS private key\n# # Type: path\n# # Default: none\n# # Required: no\n# key: /etc/ssl/private/self-signed.key\n\n# ======\n# rules:\n# ======\n\n# # Privileges of each role (privileges are inherited from roles above)\n# privileges:\n\n# # For unregistered users\n# unregistered:\n\n# # Allowed apps, or 'all' to allow all apps (do not allow services that require authentication)\n# # Type: 'all' | array\n# # Default: [ ]\n# # Required: no\n# allowed_apps: [ ]\n\n# # For guest users\n# guest:\n\n# # Allowed apps, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: ['filebrowser', 'privatebin']\n# # Required: no\n# allowed_apps:\n# - filebrowser\n\n# # For regular users\n# user:\n\n# # Allowed apps, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: ['jupyterhub', 'rstudio']\n# # Required: no\n# allowed_apps:\n# - rstudio\n\n# # For administrators\n# admin:\n\n# # Allowed apps, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: 'all'\n# # Required: no\n# allowed_apps: all\n\n# =========\n# security:\n# =========\n\n# # Rate limiting settings\n# rate_limiting:\n\n# # Enable or disable rate limiting\n# # Type: boolean\n# # Default: false\n# # Required: no\n# enabled: false\n\n# # Maximum number of requests in the given time window\n# # Type: int\n# # Default: 5\n# # Required: no\n# max_requests: 5\n\n# # Time window (in seconds, or a string describing a time span in ISO 8601 format)\n# # Type: int | string\n# # Default: 'PT1H'\n# # Required: no\n# time_window: 'PT1H'\n\n# # Session settings\n# session:\n\n# # Session lifetime (in seconds, or a string describing a time span in ISO 8601 format)\n# # Type: int | string\n# # Default: 'P1DT'\n# # Required: no\n# lifetime: 'P1DT'\n\n# =====\n# smtp:\n# =====\n\n# # SMTP server host\n# # Type: string\n# # Default: none\n# # Required: yes\n# host: smtp.gmail.com\n\n# # SMTP server port\n# # Type: integer\n# # Default: none\n# # Required: yes\n# port: 587\n\n# # SMTP server username\n# # Type: string\n# # Default: none\n# # Required: yes\n# username: joe\n\n# # SMTP server password\n# # Type: string\n# # Default: none\n# # Required: yes\n# password: joe123\n\n# # Sender name\n# # Type: string\n# # Default: 'Lungo'\n# # Required: no\n# name: Lungo\n\n# # Sender email\n# # Type: string\n# # Default: none\n# # Required: yes\n# sender: joe@gmail.com\n~/.config/lungo/users.yaml macOS ~/Library/Application Support/lungo/users.yaml Windows %USERPROFILE%\\AppData\\Local\\lungo\\lungo\\users.yaml users.yaml## Configuration file for user management\n\n# =========\n# accounts:\n# =========\n\n# # List of accounts\n# -\n\n# # Enable or disable the account\n# # Type: boolean\n# # Default: true\n# # Required: no\n# enabled: false\n\n# # Username\n# # Type: string\n# # Default: none\n# # Required: yes\n# username: joe\n\n# # Full name (first and last)\n# name:\n\n# # First name\n# # Type: string\n# # Default: none\n# # Required: yes\n# first: Joe\n\n# # Last name\n# # Type: string\n# # Default: none\n# # Required: yes\n# last: Doe\n\n# # Email address\n# # Type: string\n# # Default: none\n# # Required: yes\n# email: joe@gmail.com\n\n# # User role\n# # Type: 'guest' | 'user' | 'admin'\n# # Default: none\n# # Required: yes\n# role: user\n\n# # Extra configuration\n# extra:\n\n# # Allowed apps besides those defined in the role, or 'all' to allow all apps\n# # Type: 'all' | array\n# # Default: [ ]\n# # Required: no\n# allowed_apps:\n# - rstudio\n\n# # Override user directory\n# # Type: path\n# # Default: none\n# # Required: no\n# user_dir: /mnt/somewhere/someone\n\n# # User-specific shared directories\n# shared_dirs:\n# -\n\n# # Name of the directory after mounted (must be unique)\n# Type: string\n# Default: none\n# Required: yes\n# name: shared_readonly\n\n# # Path to the directory on the host\n# # Type: path\n# # Default: none\n# # Required: yes\n# source: /mnt/data/shared_readonly\n\n# # Whether to mount the directory as read-only or not\n# # Type: boolean\n# # Default: false\n# # Required: no\n# read_only: true\nLungo utilizes two configuration files: config.yaml, which contains general settings, and users.yaml, dedicated to user management. By default, these files are located in a platform-dependent directory, such as ~/.config/lungo/ on Linux. You can override this location by passing the --config-dir option to Lungo.
A minimal config.yaml file looks like this:
directories:\n users_dir: /home/lungo/users\n\nnetwork:\n hostname: lungo.com\n\nsmtp:\n host: smtp.gmail.com\n port: 587\n username: joe\n password: joe123\n name: Lungo\n sender: joe@gmail.com\nFor a comprehensive list of available settings, please refer to the reference for config.yaml and reference for users.yaml.
"},{"location":"getting-started/configuring-settings/#verifying-settings","title":"Verifying settings","text":"You can verify the correctness of your configuration files by running:
Terminallungo check\nAfter making any changes to the config.yaml file, you need to restart the Lungo service for the changes to take effect.
To launch Lungo, simply run the following command:
Terminallungo up\nThis will start the Lungo service as a daemon.
"},{"location":"getting-started/managing-users/","title":"Managing users","text":""},{"location":"getting-started/managing-users/#adding-a-user","title":"Adding a user","text":"To add a new user, add an entry to the users.yaml file. Here is an example of a minimal entry:
accounts:\n - username: joe\n name:\n first: Joe\n last: Doe\n email: joe@gmail.com\n role: user\nThe username and email must be unique across all users. Note that you don't need to specify a password for the user. Instead, the user will use the password reset feature to set their own password.
A user can be assigned one of the following roles:
guestuseradminEach role inherits the permissions of the previous one. For example, a user with the admin role can perform all actions that a guest or user can.
extra.user_dir field","text":"Every user has a dedicated directory for storing their files. By default, this directory is located within users_dir. However, you can set the extra.user_dir field to specify a different location for a specific user. For instance:
accounts:\n - username: joe\n - username: jane\n extra:\n user_dir: /mnt/data/jane\nSuppose you have set users_dir to /home/lungo/users in your config.yaml file. In this case, the user joe will have /home/lungo/users/joe as their user directory, while the user jane will have /mnt/data/jane as their user directory.
To remove a user, simply remove the corresponding entry from the users.yaml file. Alternatively, you can set the enabled flag to false to disable the user without removing the entry.
After making any changes to the users.yaml file, you need to restart the Lungo service for the changes to take effect.
To ensure enhanced security, it is recommended to run Lungo in a non-root user environment. To achieve this, the administrator needs to perform specific configurations as outlined in the Docker guide or the Podman guide.
To allow non-root users to bind to ports below 1024, you can utilize the setcap command:
sudo setcap 'cap_net_bind_service=+ep' \"$(command -v lungo)\"\nAlternatively, 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\nsudo sysctl net.ipv4.ip_unprivileged_port_start=80\nIn a rootless environment, proper file permissions must be set to enable non-root users on the host machine to read and write files created from within the container, and vice versa. It is recommended to create a dedicated user for Lungo and a group for sharing files between the container and the host. The following commands demonstrate this process:
Terminal# Create a group for sharing files\nsudo groupadd shared\n\n# Create a dedicated user for Lungo\nsudo useradd -m -g shared lungo\n\n# Add an existing user to the group\nsudo usermod -a -G shared <username>\n\n# Create a directory for shared files\nsudo mkdir /mnt/data/shared\nsudo chown lungo:shared /mnt/data/shared\nsudo chmod g+rws /mnt/data/shared\nFor more information on file permissions in a rootless environment, you can refer to the documentation.
Avoid using sudo su lungo to switch to the lungo user when launching Lungo in a rootless environment, as it may lead to improper functioning. Instead, set a password for the lungo user and log in normally:
sudo chpasswd <<<'lungo:<password>'\nDepending on your firewall configuration, you might need to allow access to ports 80 and 443, or any other ports that you intend to use for HTTP and HTTPS. If you are using UFW (Uncomplicated Firewall), you can use the following commands:
Terminalsudo ufw allow http\nsudo ufw allow https\nPlease make sure to adjust the firewall settings according to your specific needs and security requirements.
"},{"location":"guides/allowing-anonymous-access/","title":"Allowing anonymous access","text":"In addition to the three roles (guest, user, and admin) that can be assigned to a user, Lungo also supports anonymous access, which is associated with the role unregistered. To enable anonymous access, you need to configure the unregistered.allowed_apps field in the config.yaml file:
rules:\n privileges:\n unregistered:\n allowed_apps:\n - privatebin\n - rstudio\nTo enable anonymous access for applications that typically require user accounts, such as RStudio, you must add a user with the username anonymous in the users.yaml file:
accounts:\n - username: anonymous\n name:\n first: Anonymous\n last: User\n email: an@nymo.us\n role: guest\nThe user with the username anonymous serves as a shared account for anonymous access. The name and email fields can be set to arbitrary values (although they must still be provided). The role field must be set to guest and cannot be changed.
To limit the number of requests made by each IP address to sensitive API endpoints within a specified time window, you can enable security.rate_limiting in the configuration file. This feature is particularly useful in safeguarding against brute-force attacks targeting authentication API endpoints.
For rootless containers, it is essential to configure both the network stack and the port forwarder to use slirp4netns in order to determine the actual client IP address. Before proceeding, ensure that slirp4netns is installed on your machine.
By default, Docker and Podman employ RootlessKit as the port forwarder. For Docker, you can find instructions on changing the port forwarder here. For Podman, you don't need to do anything, as slirp4netns can be picked up automatically.
Please note that it is crucial to correctly configure the container to use slirp4netns as mentioned above before enabling security.rate_limiting. Failure to do so will result in rate limiting being applied to all requests, irrespective of the IP address, as the container won't be able to determine the actual client IP address.
Moreover, when external proxies or load balancers are present in front of the container, it is necessary to specify their IP addresses in network.trusted_proxies in order to obtain the actual client IP address.
In the config.yaml file, you can find the users_dir field, which determines the storage location for user files. By configuring this setting, you can map the home directories of local users to the corresponding location inside the container.
directories:\n users_dir: /home\nTo enable write access to directories owned by a local user from within the container, you must ensure that the UID or GID of those directories matches the user running Lungo, and that appropriate write permissions have been granted.
For instance, consider a scenario where a directory is owned by the user joe, and Lungo is running with the user lungo. In this case, the directory should be assigned to the same group as the primary group of lungo, and group write permission should be granted. For more information, please refer to the file permissions section.
graph LR\n Host(Host) --> Portal(Portal<br /><br />Openresty)\n Portal -->|Perform real IP forwarding<br />and rate limiting| Proxy(Reverse Proxy<br /><br />Openresty)\n Proxy <--->|Authorize requests| Auth(Access Control<br /><br />Oathkeeper) ---> Control\n Proxy ---> UI(Web UI<br /><br />Node.js)\n UI --->|Find accessible apps| Control\n UI ---> Backends\n\n subgraph Control [ ]\n subgraph P1 [Access Control Backends]\n subgraph P2 [ ]\n direction TB\n Authenticator(Authenticator<br /><br />Kratos) ~~~ Authorizer(Authorizer<br /><br />Keto)\n end\n end\n end\n\n subgraph Backends [ ]\n subgraph P3 [App Backends]\n subgraph P4 [ ]\n direction TB\n App1(App 1) ~~~ App2(App 2) ~~~ App0(...)\n end\n end\n end\n\n classDef Dotted stroke-dasharray: 5 5\n class Control,Backends Dotted\n classDef Padding fill: none, stroke: none\n class P1,P2,P3,P4 PaddingLungo consists of three primary components:
Lungo prioritizes security and employs various measures to minimize the attack surface. The following outlines implemented security measures:
SameSite attribute is set to Lax.Path attribute.filebrowser JupyterHub jupyterhub PrivateBin privatebin RStudio rstudio Xray xray Legend:
Icon Meaning Fully supported Partially supported Planned"}]} \ No newline at end of file diff --git a/nightly/sitemap.xml.gz b/nightly/sitemap.xml.gz index 7de906bbcb1928e26074ccc7db368f02febcdde8..448dc3113e57c070e835f380b66abca19f147e4a 100644 GIT binary patch delta 15 WcmZ3+yo{MmzMF%Cv3w)j0!9EI$OGd5 delta 15 WcmZ3+yo{MmzMF%ip=2Z50!9ELvjkrN