OSM Documentation 0.1.0 Search

6. Apps

Everything beyond the base system is installed from the App Catalog.

  • System apps are Debian's packages, updated with the system from OSM's update service: Containers, Virtual Machines, VPN, Antivirus, the Print Server and Network Boot (computers that start from the server). They are kept on the USB stick and on the server, so they install even without the internet.
  • What belongs to a page is installed on that page, not here: SMB, NFS and FTP in Settings > File Protocols, Settings > Media Streaming, Settings > SSH, Storage > iSCSI, and ZFS support in Storage > Settings. The page shows Install until it is installed, and Uninstall... at its bottom after. They install without the internet too, except ZFS support, which comes from OSM's update service.
  • Container apps run in Docker: more than 40 apps in the App Catalog, from Nextcloud and Immich to Home Assistant and Vaultwarden (What OSM does lists them all). Installing the first container app installs Containers with it, in the same job.

An installed app that the App Catalog no longer lists is still shown, marked No longer in the App Catalog. It keeps running as it was, from the copy of its description that OSM keeps with every installed app; its settings can still be changed, and you uninstall it when you no longer need it.

Installing an app

  1. Open the app's page in the App Catalog and choose Install.

  2. The dialog shows what the app needs (other apps are installed first, in the same job), its settings, its folders, and how it is reached (Addresses and ports).

    An app's folder is a shared folder itself (/volume1/Media), or a folder outside shared folders: not a folder inside one (/volume1/Media/Movies). Anyone who can write in Media could otherwise put a link in place of Movies, and the app would see whatever it led to. Give the app the shared folder, and let it find Movies inside. Nor can an app have a whole volume, a volume's own folders (@docker...), another app's data (appdata/<app>) or the system's folders: the App Catalog refuses them, and so does Create in Containers.

  3. The App Catalog shows the progress until the installation is done. The installation goes on if you close the page, and the turning ring at the top right shows it.

Each app is ready at once: OSM makes its administrator account during the installation, with a strong password, shown on the app's page in the App Catalog (Save as a file keeps it). Nothing is left with a default password, and nothing asks for a first-visit setup.

Vaultwarden is the exception: OSM makes no account for it, and anyone who reaches its page can make one (sign-up is open). Make yours, and your family's, then close sign-up: in Containers, choose More > Terminal (shell) on the vaultwarden container, type echo '{"signups_allowed": false}' > /data/config.json, then Restart Vaultwarden on its page in the App Catalog. New accounts are then refused, also after updates; the accounts made stay. To open sign-up again, delete that file (rm /data/config.json) and restart it.

The app then has an icon on the desktop and in All apps, with its own logo, and its data in a folder of its own on the volume (appdata/<app>). Uninstall... removes it; Keep its data lets you install it again later with everything in place.

How apps sign in

Each app with a web page opens from its desktop icon, signed in where OSM can. On the app's page, How it signs in (in the Sign-in section) chooses how:

  • With its own password (OSM fills it in): OSM signs in for you with the password it made. The password never reaches the browser. Only Administrators are signed in this way, since its password is the app's administrator's; other accounts see the app's sign-in page.
  • With the OSM account: each person who may use the app (App Permissions) opens it signed in as themselves; the app creates their account the first time, and OSM's Administrators are its administrators. Available for apps that support it (Grafana, Gitea, Navidrome, Paperless-ngx, VS Code), when the app is on the server's ports, not on an address of its own. The app is then reached through OSM only: phone apps that sign in to it directly need its own password. Signing out of OSM signs out of the app too.
  • On its own sign-in page: the app opens as it is.

Addresses and ports

Apps never fight over ports. Each app is reached in one of these ways:

  • Ports on the server's address: free ports, chosen at install.
  • Its own address on your network, like a separate device, so it can use any port, 80 and 53 included. Give apps a range of your network's addresses first, in Settings > Network (Addresses for apps), outside your router's DHCP range. An app that only works this way (AdGuard Home, Pi-hole) asks for the range when you install it.
  • The server's network (host), for apps that must find devices on your network (Home Assistant, Jellyfin, Plex, UrBackup; Tailscale works only this way). The app then answers on the server's own ports.

For a friendly address such as https://photos.example.com or https://nas.local/photos, see Network: an address for each app.

Priority, limits and graphics

When you install an app, or later with Settings... on its page:

  • Priority: Critical, High, Normal or Low. Higher priorities get more of the processor and the disks when the server is busy, and are the last the system stops when memory runs out.
  • Memory limit (MB) for an app that should never take more. A CPU limit is set in Containers: More on the app's container, then Priority and limits....
  • Use the graphics card: gives the app the server's graphics card (Intel, AMD or NVIDIA), for video transcoding or AI.

Network rules

Network rules, on the app's page, limit what an app may reach and who may reach it:

  • What it may reach: anywhere (the internet too); the local network only (no internet); or nothing outside the app, not even the server.
  • Who may reach it: anyone the firewall lets in, or the local network only.

Network rules are for apps on the server's ports. An app with an address of its own is a separate device on your network: its rules are your router's. An app on the server's network has no rules of its own.

Updates

System apps are updated with the system. Update on a container app's page downloads the newest version of the app and starts it; if the app does not start, the previous version comes back by itself. Each app shows its version, and App Catalog > Updates lists the apps that have a newer one, with what is new in it; an app never goes to an older version than it had. In the app's Settings...:

  • Automatic updates: in the maintenance window (Settings > Updates and Recovery), the app takes its new version if there is one, and goes back to the old one if it does not start or answer. By default, an app follows the choice for the apps in Settings > Updates and Recovery > What updates, and how. A security fix installs by itself whatever this says, while security updates do.
  • Channel: the stable versions, or newer ones (beta, nightly...) where the app has them. Newer versions may break: keep a backup of the app's data.

An app that OSM has checked on a test server (installed with its defaults, started and answering) says on its page when it last passed that check; an app that failed it is marked, and the App Catalog asks before installing it. An app that has not been checked yet shows nothing of the kind.

More apps: app sources

App sources..., in the App Catalog's side bar, adds the apps of other publishers:

  • Signed catalogs: a publisher's list of apps, signed with their key. You check the key's fingerprint once. OSM downloads each catalog again once a day and checks its signature every time: a catalog whose signature is wrong (changed by someone else, or signed with another key) is not used, and its last good copy stays.
  • CasaOS app stores: OSM installs CasaOS apps (most of CasaOS's own store) and replaces the passwords published with them by new ones for your server. A CasaOS store is not signed, so OSM takes one only over HTTPS, and only when you tick that you trust it. You can also paste a single CasaOS app.

Every app from a source is checked first. An app that would need control of the server (Docker's socket, the server's processes, system folders) is left out with the reason. An app that asks for powers over the server (privileged mode, devices, the server's network) shows each one with the reason, and installs only when you tick I know what this does: install it anyway. An app from a source never replaces an App Catalog app.

The Print Server

The Print Server shares your printers with every computer, phone and tablet of your network: AirPrint (iPhone, iPad, Mac), IPP Everywhere (Linux, Android) and Windows' Add a printer. It is CUPS, from Debian, with its own web page.

  1. Install Print Server from the App Catalog.
  2. Open its icon on the desktop: CUPS' page opens in a new tab, at https://<server>:631. The first time, your browser warns about its certificate (CUPS makes its own).
  3. Administration > Add Printer: sign in with an Administrator's name and password, choose the printer (on a USB port of the server, or on your network), and tick Share This Printer.

The printers are shared with your local network only: port 631 is open to private addresses, never to the internet. Everyone there may print; only Administrators add, change or remove printers. CUPS' page answers at the server's address (https://192.168.1.10:631) and at https://<name>.local:631. At another name (one your router gives the server), it answers Bad Request: use the address.

Containers

The Containers app manages Docker itself:

  • Containers: start, stop, restart, the log, a shell inside, details (passwords in the environment show as ***), priority and limits.
  • Create a container from any image, with its ports, folders, environment, command, and an address of its own if you want.
  • Projects: paste or edit a Compose file. Risky settings (privileged mode, the server's network or folders, Docker's socket, another app's data, a folder inside a shared folder) are listed with the reason, and refused unless you tick I know what this does: allow these settings. A folder inside a shared folder is one because Docker follows links each time it starts the container, also when it restarts it by itself: anyone who can write in that shared folder could put a link in its place. Give the container the shared folder itself instead.
  • Images: download one, and remove those that no container uses.
  • Networks: Docker's networks, and the range of addresses for apps (set in Settings > Network).

Cameras

Frigate NVR records security cameras and recognizes people, cars and animals. Its page in the App Catalog has a Cameras section:

  • Find cameras asks your local network for ONVIF cameras, and Add by its address... adds one directly. Add a camera with its user name and password: OSM sets up its largest stream for recording and its smallest for detection, and its pan-tilt-zoom controls if it has them.
  • Keep the recordings: how many days to keep everything recorded, motion, alerts and detections.

Only cameras on your local network can be added. Frigate runs on the server's ports only: you open its web page (HTTPS) and sign in as admin, with the password shown on its page in the App Catalog. Its internal interface (port 5000), which asks for no password, is closed to the other apps and to the server's accounts.

Home Assistant

The Home Assistant section of Settings > Monitoring makes the server a device in Home Assistant: its processor, memory, temperature, volumes, updates, UPS, power draw and backups, sent every minute to an MQTT broker. Home Assistant only reads: it cannot change anything on the server.

  1. Install Mosquitto from the App Catalog, or give your own broker's address in MQTT broker. Left empty, it is this server's Mosquitto, which OSM signs in to with the login made at Mosquitto's install.
  2. Turn on Send to Home Assistant, and Apply.
  3. In Home Assistant, add the MQTT integration with the same broker: the server's address, Mosquitto's port and the same login (user osm, with the password shown on Mosquitto's page in the App Catalog).

Mosquitto refuses connections without a password: every device signs in with a login. Its setting Connections without a password can accept them again, but then anyone on your network may publish and read.