## File: README.md [](https://umbrel.com/umbrelos) ## Installing umbrelOS umbrelOS is designed for the [Umbrel Pro](https://umbrel.com/umbrel-pro) and [Umbrel Home](https://umbrel.com/umbrel-home), where it includes first-class support for all features. On other devices (like Raspberry Pi or x86 systems), it’s freely available with core functionality, but support and feature availability are best-effort due to hardware differences. For a detailed feature breakdown, see our [comparison guide](https://github.com/getumbrel/umbrel/wiki/umbrelOS-on-Umbrel-Home-vs.-DIY). ### Installation guides - [Install umbrelOS on a Raspberry Pi 5](https://github.com/getumbrel/umbrel/wiki/Install-umbrelOS-on-a-Raspberry-Pi-5) - [Install umbrelOS on any x86 system](https://github.com/getumbrel/umbrel/wiki/Install-umbrelOS-on-x86-Systems) - [Install umbrelOS in a VM](https://github.com/getumbrel/umbrel/wiki/Install-umbrelOS-on-a-Linux-VM) [](https://umbrel.com/umbrelos) [](https://apps.umbrel.com) [](https://umbrel.com/umbrelos) [](https://umbrel.com/umbrelos) [](https://umbrel.com/umbrelos) [](https://umbrel.com/umbrelos) ## Building apps for umbrelOS If you're interested in building an app for umbrelOS or packaging an existing one, please refer to the [Umbrel App Framework documentation](https://github.com/getumbrel/umbrel-apps/blob/master/README.md). ## License umbrelOS is licensed under the PolyForm Noncommercial 1.0.0 license. TL;DR — You're free to use, fork, modify, and redistribute Umbrel for personal and nonprofit use under the same license. If you're interested in using umbrelOS for commercial purposes, such as selling plug-and-play home servers with umbrelOS, etc — please reach out to us at partner@umbrel.com. [](https://github.com/getumbrel/umbrel/blob/master/LICENSE.md) [umbrel.com](https://umbrel.com) --- ## File: containers/tor/README.md [](https://github.com/getumbrel/umbrel-tor) [](https://github.com/getumbrel/umbrel-tor/actions?query=workflow%3A"Docker+build+on+push") [](https://hub.docker.com/repository/registry-1.docker.io/getumbrel/tor/tags?page=1) # ☂️ Tor A simple Docker image for Tor ## 🛠 Build Tor Docker image ### Build ```sh docker build -t getumbrel/tor . ``` ### Run ```sh docker run --rm -u 1000:1000 -e HOME=/tmp getumbrel/tor ``` --- ## File: containers/app-proxy/README.md [](https://github.com/getumbrel/umbrel-app-proxy) [](https://github.com/getumbrel/umbrel-app-proxy/actions?query=workflow%3A"Docker+build+on+push") [](https://hub.docker.com/repository/registry-1.docker.io/getumbrel/app-proxy/tags?page=1) # ☂️ App Proxy App-proxy is a transparent HTTP proxy to add authentication to Umbrel apps. Every HTTP request and Websocket connection goes through the proxy and each request has the session token checked for validity. The session token is set via [App-auth](https://github.com/getumbrel/umbrel/tree/master/containers/app-auth). It runs by-default as a containerized service. ## 🚀 Getting started If you are looking to run Umbrel on your hardware, you do not need to run this service on it's own. Just download [Umbrel OS](https://github.com/getumbrel/umbrel-os/releases) and you're good to go. ## 🛠 Running app-proxy Make sure [`umbrel-manager`](https://github.com/getumbrel/umbrel-manager) and [`app-auth`](https://github.com/getumbrel/umbrel/tree/master/containers/app-auth) are running and available. ### Development and testing ```sh cd $UMBREL_ROOT/containers/app-proxy/test ./test.sh docker-compose.app1.yml ``` Within the `test` directory there are several test apps to test different functionality such as Websocket and SSE with the proxy. ### Environment variables (dev/testing) The following environment variables are set in `.env` file of the project's root: | Variable | Description | Default | | --------------------------------- | ----------------------------------------------------------------------------- | ---------------------------- | | `LOG_LEVEL` | Log level for the proxy (`http-proxy-middleware`) | `info` | | `PROXY_PORT` | HTTP proxy container port | `4000` | | `PROXY_AUTH_ADD` | `true`/`false` as to whether the app should be protected with authentication | `true` | | `PROXY_AUTH_WHITELIST` | A comma seperated list of paths that are whitelisted (e.g. `/public/*`) | | | `PROXY_AUTH_BLACKLIST` | A comma seperated list of paths that are whitelisted (e.g. `/admin/*,/api/*`) | | | `APP_HOST` | App's frontend container hostname/IP | | | `APP_PORT` | App's frontend container port | | | `APP_MANIFEST_FILE` | Location of app's manifest file | `/extra/umbrel-app.yml` | | `UMBREL_AUTH_PORT` | App-auth's exposed (port-forwarded) port | `2000` | | `UMBREL_AUTH_SECRET` | A shared secret for manager, app-auth and app-proxy | `umbrel` | | `UMBREL_AUTH_HIDDEN_SERVICE_FILE` | Location of app-auth's Tor HS hostname | `/var/lib/tor/auth/hostname` | | `MANAGER_IP` | Umbrel's manager IP | `10.21.21.4` | | `MANAGER_PORT` | Umbrel's manager container port | `9005` | --- ## File: containers/app-auth/README.md [](https://github.com/getumbrel/umbrel-app-auth) [](https://github.com/getumbrel/umbrel-app-auth/actions?query=workflow%3A"Docker+build+on+push") [](https://hub.docker.com/repository/registry-1.docker.io/getumbrel/app-auth/tags?page=1) # ☂️ App Auth App-auth is a simple authentication and redirection system for Umbrel apps. It ensures (where applicable) that apps are password (and OTP) protected. It runs by-default as a containerized service. ## 🚀 Getting started If you are looking to run Umbrel on your hardware, you do not need to run this service on it's own. Just download [Umbrel OS](https://github.com/getumbrel/umbrel-os/releases) and you're good to go. ## 🛠 Running app-auth Make sure [`umbrel-manager`](https://github.com/getumbrel/umbrel-manager) are running and available. ### Development and testing ```sh cd $UMBREL_ROOT/containers/app-auth/test ./test.sh ``` ### Environment variables (dev/testing) The following environment variables are set in `.env` file of the project's root: | Variable | Description | Default | | ------------- | ------------- | ------------- | | `PORT` | Web server port within container | `2000` | | `UMBREL_AUTH_SECRET` | A shared secret for manager, app-auth and app-proxy | `umbrel` | | `MANAGER_IP` | Umbrel's manager IP | `10.21.21.4` | | `MANAGER_PORT` | Umbrel's manager container port | `9005` | --- ## File: packages/ui/app-auth/README.md # Local testing Make sure umbreld is running ``` cd packages/umbreld npm run dev ``` Then in another terminal ``` cd packages/ui pnpm run app-auth:dev ``` Go to `localhost:3001` and make sure you're logged out. Then, assuming `transmission` is installed and running, open: http://localhost:2001/app-auth/?origin=host&app=transmission&path=%2Ftransmission%2Fweb%2F In production, it would be: http://localhost:2000/?origin=host&app=transmission&path=%2Ftransmission%2Fweb%2F Login with password and 2fa should work and you should be redirected to the right page. --- ## File: packages/ui/src/routes/README.md Non-route files and folder should be prefixed with an underscore. This is to prevent confusion. --- ## File: packages/ui/README.md # umbrelOS UI ## Getting umbrelOS running locally ### Prerequisites `npm` and `pnpm` is installed. First install `pnpm`. One way is via `brew install pnpm` on mac, assuming you have homebrew installed. ### Clone the repo and checkout the `mark` branch `git clone -b mark git@github.com:getumbrel/private-umbrel.git` ### Go into the repo `cd private-umbrel` ### Get frontend running 1. `cd packages/ui` 1. `pnpm install` 1. `pnpm run dev` ### Get backend running 1. Get back to the root of the repo and `cd` into umbreld: `cd packages/umbreld` 1. Make the dir for the data: `mkdir data` 1. `npm install` 1. `npm run dev` ## Sharing semi-publicly (on Mac) 1. [Get the CLI](https://tailscale.com/kb/1080/cli/#using-the-cli) 2. Add this to your `.zshrc` or `.bashrc`: ```sh alias tailscale="/Applications/Tailscale.app/Contents/MacOS/Tailscale" ``` 3. Run `tailscale serve`: ```sh tailscale serve http:3000 / http://127.0.0.1:3000 ``` 4. For production: ```sh tailscale serve http:4000 / http://127.0.0.1:4000 ``` Running on HTTP for now. HTTPS would be a bit more complicated. The prod build is especially important for getting a true sense of performance on mobile since the dev build will have extra cruft. --- # Decisions / common patterns ## `keyBy` Using `remeda` instead of `lodash` because it's more typesafe. Lodash `keyBy` adds 14kb after minifcation and doesn't return proper types. ## `foobarDescription` format for static data For lots of static data we want to maintain order and have it indexed. For a nav menu, we want a slug and a string for each element. We call them descriptions if it's an array with each element having an `id` and `label`. So we do this: ```ts const navDescriptions = [ { id: 'home', label: 'Home' } { id: 'about', label: 'About' } ] as const // <-- important const navDescriptionsKeyed = keyBy(navDescriptions, 'id') ``` ## Adding view transition support to elements EX: ```tsx Box ``` You can then search the repo for `viewTransitionName` to find them all ## Event handler naming in React components Use `onFooBarClick` rather than `onClickFooBar` ## No barrel files Vite doesn't like them. Haven't tested how bad they are for performance, though. https://vitejs.dev/guide/performance#avoid-barrel-files ## tRPC Prefer `trpcReact` over `trpcClient` because it lets you manage error and loading state, caching, and invalidation. More info here: https://trpc.io/docs/client/vanilla#when-not-to-use-the-vanilla-client --- # TROUBLESHOOTING ## TypeScript errors in code that don't make sense in VSCode Restarting the TS server via the command palette fixes it. I haven't run into a situation where this doesn't fix it. --- ## File: scripts/backup/README.md # Automatic Encrypted Backups The backups are encrypted client side before being uploaded over Tor and are padded with random data. Backups are made immediately as soon as the channel state changes. However, Umbrel also makes decoy backups at random intervals to prevent timing-analysis attacks. These features combined ensure that the backup server doesn't learn any sensitive information about the user's Umbrel. - The IP address of user is hidden due to Tor. - User's channel data are encrypted client side with a key only known to the Umbrel device. - Random interval decoy backups ensure the server can't correlate backup activity with channel state changes on the Lightning network and correlate a backup ID with a channel pubkey. - Random padding obscures if the backup size has increased/decreased or remains unchanged due to it being a decoy. Due to the key/id being deterministically derived from the Umbrel seed, all that's needed to fully recover an Umbrel is the mnemonic seed phrase. Upon recovery the device can automatically regenerate the same backup id/encryption key, request the latest backup from the backup server, decrypt it, and restore the user's settings and Lightning network channel data. There is currently no way to disable backups or recover from them in the dashboard yet. Both of these features will be introduced in the coming updates.