# HexOS

Source: https://frameleaf.app/docs/nas/hexos/

Frameleaf runs on HexOS through [Frameleaf Manager](https://frameleaf.app/docs/start/install/). You install Manager as a HexOS app, and Manager then installs the photo library, keeps database backups and handles Frameleaf updates. HexOS gives Manager its own folders inside the storage locations you already use, so there's nothing to type in apart from your Manager password.

Today you install it with a Custom Install script. A one-click listing in the HexOS app catalog is coming soon: it's waiting for approval from HexOS.

| | Custom Install script | App catalog (coming soon) |
| --- | --- | --- |
| How | Turn on experimental features, then paste the Frameleaf script into **Custom Install** | **Apps**, search for **Frameleaf**, **Install** |
| Manager version | The newest Manager release at the time you install or update | The release listed in the HexOS catalog |
| Updates | HexOS offers an update when a newer Manager image is published | HexOS offers each new Manager release |
| Best for | Everyone today, and anyone who wants the newest Manager straight away | Most people, once Frameleaf is listed |

Both install exactly the same Manager with the same folders, so you can move from one to the other later without losing anything. See [Switch between the two](#switch-between-the-catalog-and-custom-install).

## Before you begin

**Storage locations.** Frameleaf uses three of the locations in HexOS **Settings → Locations**. If one isn't set yet, HexOS asks you to choose it before it installs anything.

| HexOS location | Frameleaf folder | What's kept there |
| --- | --- | --- |
| Applications (performance) | `frameleaf/manager` | Manager's settings, your Manager administrator and its operation history |
| Applications (performance) | `frameleaf/databases` | The Frameleaf database. Manager creates a new directory here for each library and never reuses an old one |
| Photos | `frameleaf` | Your original photos and videos, with thumbnails, encoded videos and other files Frameleaf creates |
| Applications (capacity) | `frameleaf/backups` | Encrypted database backups and recovery settings |

The performance location is usually on SSDs, which keeps the database fast. The capacity location is usually your large hard-drive pool, so database backups end up on different disks from the database itself. HexOS creates every folder for you.

**Hardware.** Allow at least 4 processor cores, 8 GB of memory and 10 GB of free space for the apps, plus room for your library. Face recognition and smart search need more. See [Requirements](https://frameleaf.app/docs/start/requirements/).

**Ports.** Manager starts on port `2282`. If another app already uses it, HexOS gives Manager the nearest free port, and **Launch** in HexOS opens it. The photo library normally uses `2283`, and you can choose another port during setup. If Immich is installed on this server through HexOS, it already uses `2283`, so pick a different port for Frameleaf, such as `2284`.

**Docker access.** Manager installs Frameleaf's server, database and optional machine learning as separate containers, so it needs access to Docker on your server. Manager drops every other privilege when it starts. Keep Manager on your home network and don't forward Manager's port to the internet.

## Install with a Custom Install script

Every [Frameleaf Manager release](https://github.com/Frameleaf/frameleaf-app/releases?q=%22Frameleaf+Manager%22&expanded=true) includes `frameleaf-manager.hexos.json`, a HexOS install script that always runs the newest Manager image.

### 1. Download and check the script

1. Open the newest **Frameleaf Manager** release from the link above.
2. Under **Assets**, download `frameleaf-manager.hexos.json` and `SHA256SUMS` into the same folder.
3. Check the download. On a Mac or Linux computer, run this in that folder:

   ```sh
   shasum -a 256 --check --ignore-missing SHA256SUMS
   ```

   It prints `frameleaf-manager.hexos.json: OK`. On Windows, run `Get-FileHash .\frameleaf-manager.hexos.json` in PowerShell and compare the hash with the `frameleaf-manager.hexos.json` line in `SHA256SUMS`. If it doesn't match, download the file again and don't use it.

The release's signed `manager-manifest.json` records the script's exact contents. To check that signature too, follow [Verify Manager installers](https://github.com/Frameleaf/frameleaf-app/blob/main/packaging/nas/README.md).

### 2. Turn on Custom Install

In HexOS, go to **Settings → Preferences** and turn on **Experimental features**. If your HexOS also shows **Expert mode** under **Advanced Settings**, turn that on too. This adds **Custom Install** to Apps. You only need to do this once.

### 3. Paste the script and install

1. Open `frameleaf-manager.hexos.json` in a plain text editor, such as TextEdit, Notepad or VS Code. Select all of it and copy it.
2. In HexOS, open **Apps** and choose **Custom Install**.
3. Click in the script editor, select everything already there and delete it, including any leftover `{ }`. Then paste the Frameleaf script.
4. Select **Install**. If a location isn't set yet, HexOS asks you to choose it.
5. Wait for Frameleaf to show as running, then continue with [Open Manager and set up your library](#open-manager-and-set-up-your-library).

If the editor shows an error, the paste was probably cut short. Copy the whole file again and replace the editor's contents.

## Install from the HexOS app catalog (coming soon)

:::note[Coming soon]
Frameleaf is waiting for approval in the HexOS app catalog, so you won't find it in **Apps** yet. Until it's listed, [install with a Custom Install script](#install-with-a-custom-install-script). You can move to the catalog version later without losing anything.
:::

Once Frameleaf is listed:

1. In HexOS, open **Apps** and search for **Frameleaf**.
2. Select **Install**. HexOS checks that your Applications and Photos locations are set and offers to set any that are missing.
3. Follow the install progress in the activity center. HexOS creates the Frameleaf folders and starts Frameleaf Manager. The first start can take a few minutes while HexOS downloads Manager.
4. Once the app shows as running, continue with [Open Manager and set up your library](#open-manager-and-set-up-your-library).

## Open Manager and set up your library

1. From a device on your home network, open the Frameleaf app in HexOS and select **Launch**, or go to `https://<your-server's-address>:2282`. If HexOS gave Manager another port, use **Launch**.
2. Your browser warns that the connection isn't private. Manager makes its own certificate for your home network, and browsers don't know it yet. Continue to the page: in Chrome or Edge choose **Advanced** and then **Proceed**, in Safari choose **Show Details** and then **visit this website**, and in Firefox choose **Advanced** and then **Accept the Risk and Continue**.
3. On **Secure your Manager**, enter your name and a password of at least 14 characters, then select **Create administrator**. This only works from your home network, and only until Manager has an administrator, so do it soon after installing. See [Create your Manager administrator](https://frameleaf.app/docs/start/install/#3-create-your-manager-administrator).
4. On **Choose how to begin**, select **Set up Frameleaf** under **Set up a new library**. Manager has already filled in your HexOS folders:
   - **Media location**: the `frameleaf` folder in your Photos location.
   - **PostgreSQL appdata location**: the `frameleaf/databases` folder in your Applications location.
   - **Database backup destination**: the `frameleaf/backups` folder in your capacity location.
5. Choose the **Frameleaf port**, normally `2283`, and a **Frameleaf release**. Turn on **Machine learning** if you want face recognition and smart search.
6. Tick the startup checkbox. HexOS and Docker start Frameleaf when the server starts, so nothing else needs to.
7. Select **Check this server**, fix anything it lists, then select **Review installation** and **Install Frameleaf**. You can close the page while Manager works. See [Check this server on HexOS](#check-this-server-on-hexos).

When Manager shows **All done**, carry on with [Finish your photo account and phone setup](https://frameleaf.app/docs/start/install/#5-finish-your-photo-account-and-phone-setup) and [Save your recovery information](https://frameleaf.app/docs/start/install/#6-save-your-recovery-information). Your photo library opens at `http://<your-server's-address>:2283`, or the port you chose.

If you have a Frameleaf backup from another server, choose **Restore a backup** on **Choose how to begin** instead. See [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/).

### Check this server on HexOS

**Check this server** looks at Docker, your folders, the port, the network, the signed release and memory before anything is downloaded, and lists every problem at once with steps for HexOS. See [Check this server](https://frameleaf.app/docs/start/install/#check-this-server).

- **Docker is too old.** Update HexOS to the latest version, then open Manager again.
- **Manager can't use Docker.** Check Applications are running in HexOS, or restart the server.
- **Not enough room in Docker's storage.** Free some space on the drive that holds your applications, or remove apps you no longer use.
- **Manager can't reach a folder.** Check the Applications location you chose for Frameleaf is on a drive inside this server. If you changed that location, choose it again for Frameleaf in HexOS.
- **This server has less than 8 GB of memory.** Frameleaf still works, but faces and smart search can run out of memory. Select **Turn off faces and smart search**, or carry on.

For every message and its fix, see [Problems Check this server can report](https://frameleaf.app/docs/help/troubleshooting/#problems-check-this-server-can-report).

### Fast drives on HexOS

HexOS chooses the drives for you. The database goes in your Applications (performance) location, which is usually on SSDs, and thumbnails stay with your photos in the Photos location. Manager's **Storage** page shows where each one is, how much room it uses and how much is left on its drive. See [Move data to another drive](https://frameleaf.app/docs/admin/move-data-to-another-drive/).

## Keep your library safe

- **Database:** use **Make one now** on **Backups** in Manager. Backups go to the `frameleaf/backups` folder in your capacity location, encrypted. Manager also saves a recovery point before every Frameleaf update.
- **Photos and videos:** Manager's backups don't include them. Back up the whole `frameleaf` folder in your Photos location, including `thumbs`, which also holds edited versions that can't be recreated.
- **Recovery information:** export Manager's configuration and recovery key and keep them away from this server. Without them, a backup can't be restored on a new server.
- **Snapshots:** before HexOS updates the Frameleaf app, it takes a snapshot of Manager's folder and the database folder and keeps the three most recent. They help HexOS support roll back a failed update. They don't replace backups, because they're stored on the same disks.

See [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/).

## Updates

There are two things to update, and each has its own place:

- **Frameleaf Manager:** HexOS shows **Update** on the app's **Application info** card when a new Manager is available. The app has to be running to update. Your Manager settings, administrator and library stay as they are.
- **Your photo library:** Manager installs new Frameleaf versions automatically and saves a database recovery point before each one. To choose when yourself, turn **Install updates automatically** off under **Updates**. See [Upgrading](https://frameleaf.app/docs/admin/upgrading/#with-frameleaf-manager).

## Switch between the catalog and Custom Install

Once Frameleaf is listed in the HexOS app catalog, you can move your Custom Install over to it. HexOS won't install a catalog app while a custom app with the same name is installed, so:

1. In Manager, open **Services**, choose **Stop stack** and confirm **Stop services**.
2. In HexOS, uninstall the Frameleaf app. This removes Manager's container only. Your folders and everything in them stay.
3. Install Frameleaf from the catalog as above.
4. Open Manager. It finds its saved settings, so sign in with your existing Manager password. On **Services**, choose **Start stack**.

The same steps work in the other direction.

## Remove Frameleaf

1. In Manager, open **Services**, choose **Stop stack** and confirm **Stop services**.
2. In HexOS, uninstall the Frameleaf app.

HexOS leaves the Frameleaf folders in your locations. Only delete them once you're sure you have a copy of your photos and videos elsewhere: the `frameleaf` folder in your Photos location holds your originals.

## Switching from Immich on HexOS

The HexOS install gives Manager access to Frameleaf's own folders only. It can set up a new library or restore a Frameleaf backup, but it can't import an Immich app that HexOS installed. Leave Immich running on its own port while you try Frameleaf, and keep it until your photos are in Frameleaf.

To bring an Immich library over on another kind of server, see [Switch from Immich](https://frameleaf.app/docs/migrate/from-immich/).

## Troubleshooting

**HexOS says a location is missing.** Set it in **Settings → Locations**, then select **Install** again.

**Manager isn't on port 2282.** Another app had that port when you installed, so HexOS chose the nearest free one. Open Manager with **Launch** in HexOS.

**Manager won't let you create the administrator.** Open Manager from a device on the same home network as the server, not over a VPN or the internet. If an administrator already exists, sign in with its password instead.

**Manager refuses the Frameleaf port.** Another app, often Immich, is using it. Choose a different port, such as `2284`.

**The photo library doesn't open after a server restart.** Open Manager. **Services** shows each part of Frameleaf and its health. Use **Start stack** if it's stopped, or check its logs from there.
