DOCSEARCHbyAlgolia
Submit Docs

umbrelOS Home Server Operating System

repository·master·Indexed 9 days ago

https://github.com/getumbrel/umbrel

A home server operating system designed to simplify self-hosting and maintain data ownership. It includes a user-friendly interface for running various services and applications, featuring components like app-auth for password and OTP protection, app-proxy for session token verification, and support for Raspberry Pi and AMD64 hardware.

Tokens
38.2K
Snippets
120
Records
169
Agent score
95%

What's inside umbrelOS

  3. Identify the correct umbrelOS variant

    master

    umbrelOS is distributed in three main variants depending on your hardware and existing installation method:

    • umbrelos-pi: Rugix-native version for Raspberry Pi devices.
    • umbrelos-amd64: Rugix-native version for AMD64 devices.
    • umbrelos-mender-amd64: Rugix-based but Mender-compatible version for AMD64 devices.

    Important: If you are using a legacy device that was originally provisioned with Mender, you must use the umbrelos-mender-amd64 variant. This variant includes specific configurations to allow a safe migration from Mender to Rugix, including state migration hooks and GRUB interfacing for A/B switching.

  5. Test app-auth locally

    master

    To test the app-auth package locally, you must have umbreld running in development mode. Follow these steps:

    1. Start umbreld: In a terminal, navigate to the umbreld package and run the development command.
    2. Start app-auth: In a separate terminal, navigate to the ui package and run the app-auth:dev script.
    3. Verify logout state: Navigate to http://localhost:3001 and ensure you are logged out.
    4. Simulate app authentication: Assuming an app like transmission is running, navigate to the local authentication URL with the required query parameters. If successful, you should be able to log in via password and 2FA and be redirected to the target path.

    Local Authentication URL Format: http://localhost:2001/app-auth/?origin=host&app=<APP_NAME>&path=<APP_PATH>

    # Terminal 1: Start umbreld
cd packages/umbreld
npm run dev

# Terminal 2: Start app-auth
cd packages/ui
pnpm run app-auth:dev

  6. Run App Proxy tests

    master

    To test the proxy functionality (including WebSocket and SSE support) in a development environment, navigate to the test directory and execute the test script with a specific docker-compose configuration. The test directory contains multiple test apps for different scenarios.

    cd $UMBREL_ROOT/containers/app-proxy/test
./test.sh docker-compose.app1.yml

  7. Perform a factory reset using rugix-ctrl

    master

    Factory resets are managed via the Rugix ctrl mechanism. This process reboots the system and removes the state on the data partition.

    Standard Reset

    Run the following command to trigger a reset:

    rugix-ctrl state reset

    Note: In RAID configurations, a state-reset/prepare hook is used to ensure both the RAID and the main data partition are wiped.

    Recommended: Reset with Backup

    Because removing state can be time-consuming during boot, it is recommended to use the --backup flag. This renames the old state directory instead of deleting it immediately, allowing umbreld to clean it up after a successful boot.

    The old state will be renamed following this pattern: /run/rugix/mounts/data/state/default $\rightarrow$ /run/rugix/mounts/data/state/default.XXXXXXXXXXXXXX (where XXXXXXXXXXXXXX is the timestamp).

    rugix-ctrl state reset --backup

  8. Migrate AMD64 devices from Mender to Rugix

    master

    To migrate an AMD64 device from a Mender-based installation to Rugix, install the umbrelos-mender-amd64.mender update artifact.

    The migration process involves a Rugix boot/post-init hook (10-migrate-state.sh) that handles the directory structure on the data partition.

    Migration Workflow:

    1. Install the Mender update artifact.
    2. The system boots with a symlink /data/umbrel-os pointing to the bare data partition.
    3. Once the system is committed, the hook atomically replaces the symlink with the actual directory from the data partition.
    4. A reboot is required after the commit to trigger the migration. The umbreld daemon may automatically check for the symlink and reboot the system if necessary.

  9. Build apps for umbrelOS

    master

    To develop new applications specifically for the umbrelOS ecosystem or to package existing services for use on an Umbrel server, you must use the Umbrel App Framework.

    Refer to the official Umbrel App Framework documentation for technical specifications, packaging requirements, and development guidelines.

  10. Run App Auth for development and testing

    master

    To run the development and testing suite for app-auth, navigate to the test directory within the project and execute the test script. Ensure that umbrel-manager is running and available on your system before starting.

    cd $UMBREL_ROOT/containers/app-auth/test
./test.sh

  11. Install umbrelOS on various hardware

    master

    umbrelOS is a home server OS designed for self-hosting. While it provides first-class support for Umbrel Pro and Umbrel Home hardware, it can be installed on other devices with core functionality.

    Choose the appropriate guide based on your target hardware:

    • Raspberry Pi 5: Use the dedicated Raspberry Pi 5 installation guide.
    • x86 Systems: Use the guide for any standard x86-based hardware.
    • Virtual Machines: Use the guide for installing umbrelOS within a Linux VM.

    Note: On non-Umbrel hardware (DIY installations), feature availability and support are provided on a best-effort basis.

  12. Text file constraints and safety logic

    master

    The TextViewer employs several constraints to ensure stability and prevent the UI from attempting to render binary data as text:

    • Max File Size: Files larger than 50MB (1_048_576 * 50) will throw an error and trigger a download dialog instead of opening the editor.
    • Binary Detection: The component uses a looksLikeBinary check. A file is rejected if:
      • It contains NUL bytes (\0).
      • The ratio of control characters (non-whitespace characters with ASCII code < 32) exceeds 2% (MAX_CONTROL_CHARACTER_RATIO).
    • UTF-8 Enforcement: Uses TextDecoder with {fatal: true} to ensure strict UTF-8 compliance.