# Synology

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

**Frameleaf Manager for Synology** puts your whole photo server inside DSM: library setup, service controls, storage, database backups and updates, all in a native DSM window. Install the SPK with **Package Center → Manual Install**, open it from the DSM main menu, and a guided assistant does the rest.

[![Frameleaf Manager in its native Synology window, showing library health, NAS storage, running services and recent activity.](https://frameleaf.app/shots/synology/overview.webp)](https://frameleaf.app/shots/synology/overview.webp)

*Your library at a glance, right inside DSM. Screenshots show the Synology interface with an example library; select an image to enlarge it.*

## Before you begin

- **DSM 7.2.2-72806 or later**.
- **Container Manager 1432 or later**, installed and running from Package Center. The native app uses it to run Manager and the library services.
- A DSM account in the **administrators** group. Frameleaf Manager appears in the DSM menu for administrators.
- A 64-bit `amd64` or `arm64` NAS that runs that Container Manager version. Allow **6 GB RAM minimum, 8 GB recommended**; with 4 GB, leave local machine learning disabled. See [Requirements](https://frameleaf.app/docs/start/requirements/).
- Local storage for the database, enough space for your media and generated files, and an independent backup destination.

Already running Frameleaf or Immich by hand? Keep its folders, credentials and backups. The package doesn't take over an existing stack: bring an Immich library across with **Import an Immich library** in step 4, or keep updating your manual stack as before (see [Existing manual Container Manager installations](#existing-manual-container-manager-installations)).

## 1. Prepare four folders

In **Control Panel → Shared Folder**, create a dedicated `frameleaf` shared folder on your chosen volume. In **File Station**, create these four folders inside it before starting the package installer:

| Installer field | Example host path | Contents |
| --- | --- | --- |
| Manager state folder | `/volume1/frameleaf/manager` | Manager administrator, settings, local setup secrets and operation history |
| Media folder | `/volume1/frameleaf/media` | Original photos and videos, previews and generated library files |
| Database parent folder | `/volume1/frameleaf/databases` | New PostgreSQL directories created by Manager |
| Encrypted database backup folder | `/volume1/frameleaf/backups` | Database checkpoints and recovery configuration |

Use your actual volume number. All four paths must already exist and be separate, not nested inside one another. Use absolute `/volumeN/...` paths with letters, numbers, hyphens, underscores and periods; the installer rejects spaces, symbolic links and `..` segments. Check the folder permissions so Manager and its library services can write to them.

Keep the database on a local disk, preferably an SSD, outside Container Manager's internal Docker storage and not on an SMB or NFS mount. Manager creates a fresh PostgreSQL subdirectory there for you.

Because the folders live outside the package, your data stays put through package updates and even removal. Back up the database and the complete media tree independently too.

## 2. Install the released SPK

The current Synology Manager package is **0.1.0-16**. Download the [approved SPK](https://github.com/Frameleaf/frameleaf-synology-releases/releases/download/synology-v0.1.0-16/FrameleafManager-noarch-0.1.0-16.spk) and its matching [SHA256SUMS](https://github.com/Frameleaf/frameleaf-synology-releases/releases/download/synology-v0.1.0-16/SHA256SUMS) from the [public release](https://github.com/Frameleaf/frameleaf-synology-releases/releases/tag/synology-v0.1.0-16). Anyone can download them; no GitHub access needed.

Verify the SPK before uploading it. On macOS, run this in the folder containing the downloaded files:

```sh
shasum -a 256 -c SHA256SUMS
```

On Linux, use `sha256sum -c SHA256SUMS`. The SPK should report `OK`. The SHA-256 for this version is:

```text
470dbbe01d41e619a2e325ae0a7bc9a855bcd9c0044b8e9db24df9de2b2c3133
```

1. Sign in to DSM using **HTTPS** as an administrator.
2. Open **Package Center**, install **Container Manager** if needed, and check it's running.
3. Choose **Manual Install** and upload the verified SPK. If DSM shows a third-party publisher warning, check that the package is **Frameleaf Manager** from **Frameleaf**, then confirm.
4. Enter the four existing folder paths from the table above.
5. Enter the **NAS HTTPS hostname or IPv4 address** you used to open DSM. Enter only the hostname or address, without `https://`, a port or a path.
6. Check the **DSM HTTPS port** (normally `5001`) and **Manager connection port** (normally `9443`). The Manager port must be unused, `1024` or higher and different from the DSM port. This connection stays local to the NAS.
7. Review the settings and complete the installation. Wait for Package Center to show the package as running.

For example, opening DSM at `https://diskstation.home:5001` means entering `diskstation.home`, DSM port `5001` and Manager connection port `9443`. The native app then runs through your existing DSM HTTPS connection at `https://diskstation.home:5001/frameleaf-manager/`, so there's no need to open port `9443` in your browser or firewall.

## 3. Open the app and create its administrator

1. Sign in to DSM as an administrator at the **exact HTTPS hostname and port** you entered during installation, with a DSM certificate your browser trusts.
2. Open **DSM main menu → Frameleaf Manager**, or choose **Open** from its Package Center page.
3. Enter your Manager administrator name and a password of at least **14 characters**, then select **Create administrator**. Your DSM administrator session authorizes this, so there's no claim key to find.

Manager has its own administrator account, separate from DSM and from your photo library account. Keep DSM's administrative HTTPS address on your trusted network.

## 4. Create your photo library

[![Synology library setup assistant with choices to create a new library, import an Immich library or restore a database backup.](https://frameleaf.app/shots/synology/welcome.webp)](https://frameleaf.app/shots/synology/welcome.webp)

*One place to start a fresh library, bring an existing Immich library or recover from a database backup.*

1. Open **Library setup** and select **Create a new library**.
2. Enter your **Library name** and select a **Release** from the list.
3. Choose the **Media folder** you set up during package installation.
4. Check the **Database parent folder**. Manager creates a new PostgreSQL 19 directory here and keeps any earlier ones.
5. Choose the **Library web port**, normally `2283`, and whether to turn on local **Machine learning**. On a NAS with limited memory, start with it off.
6. Select **Review installation** and check the release, storage paths, service changes and recovery information.
7. Confirm the storage, downtime and recovery summary, then select **Confirm and continue**.

[![Synology setup assistant showing separate local database, encrypted database backup and media folders, plus the library port and machine learning choice.](https://frameleaf.app/shots/synology/setup-storage.webp)](https://frameleaf.app/shots/synology/setup-storage.webp)

*Review where everything will live before installing the library. The assistant uses the folders prepared on your NAS.*

The Synology SPK installs Manager, and Manager installs the photo server from an authenticated application release with a signed NAS bundle. The releases it offers are the ones built for your NAS, with the right images and PostgreSQL version.

Feel free to close the DSM window while an operation runs; your library keeps going. Reopen Manager and check **Activity** for progress, or for a recovery action if something was interrupted.

For an existing Immich installation, select **Import an Immich library** and follow [Switch from Immich](https://frameleaf.app/docs/migrate/from-immich/). Keep the source database and media backup intact, check the discovered source and keep its media locations as they are.

## 5. Open Frameleaf and connect your devices

When the library is ready, select **Open library**, or open `http://<nas-address>:2283` from your home network using the port you chose. Create your photo library administrator and set up processing, then follow [First steps](https://frameleaf.app/docs/start/first-steps/) to bring in your collection and connect your devices.

The photo library administrator is separate from your DSM and Manager administrator accounts. Setup only works from your home network and only until the library has an administrator, so finish it soon after installing.

Back in **Library setup**, select **Finish setup** when it appears. Open a few photos, videos and albums to check them; thumbnails, faces and search keep processing in the background.

## Manage your library in DSM

[![Native Synology Services page with Frameleaf and PostgreSQL status, start, stop, restart and log controls.](https://frameleaf.app/shots/synology/services.webp)](https://frameleaf.app/shots/synology/services.webp)

*Service controls and logs stay close at hand. Manager remains available when the photo library is stopped.*

| Page | Use it for |
| --- | --- |
| **Overview** | Library information, service health and opening your photo library |
| **Library setup** | Creating a library, importing Immich and completing preparation |
| **Services** | Start, stop, restart and **View log** for managed services |
| **Storage** | Mounted folders, available space and the current database location |
| **Database backups** | Encrypted checkpoints, recovery keys and reviewing a restore |
| **Updates** | Reviewing eligible releases for the photo library |
| **Activity** | Operation history, progress and interrupted-operation recovery |
| **Settings** | Manager administrator and protected configuration export |

## Protect your library

[![Synology Database backups page with encrypted database checkpoints, recovery key export and a reminder to protect photos and videos separately.](https://frameleaf.app/shots/synology/database-backups.webp)](https://frameleaf.app/shots/synology/database-backups.webp)

*Database checkpoints protect the library's records. Keep a separate copy of your photos and videos too.*

1. Open **Database backups → Create backup** for an encrypted database checkpoint.
2. Choose **Export recovery key** and keep the key privately away from the NAS.
3. In **Settings**, choose **Export protected configuration**, confirm your Manager password and store the export privately. It contains recovery secrets.
4. Back up the complete media tree, including previews and edited artifacts, any external libraries and the Manager state folder to an independent destination.

To recover, make the original media locations available, unlock **Database backups** with your recovery key and choose **Review restore** beside a checkpoint. Check the destination and media mappings, then confirm. Manager restores into a new database directory, leaving the current one untouched; photos and videos come back from your separate media backup. See [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/).

## Update the package and the photo library

- **Synology app and Manager:** download the newer SPK and its checksum from Frameleaf, verify them, then use **Package Center → Manual Install**. The upgrade keeps your storage paths, HTTPS hostname and ports. Keep those folders available while it runs.
- **Photo library:** open **Updates** in the native app, choose **Review update** for a release, check its checkpoint and service changes, and confirm.

Back up your database and media before either update. Afterwards, reopen the app and check sign-in, photos, videos and background processing. If an update fails, **Activity** shows the error and the recovery action to take. See [Upgrading](https://frameleaf.app/docs/admin/upgrading/).

To uninstall, first stop the library in **Services** and check its services have stopped. Removing the package leaves your state, media, database and backup folders exactly where they are, so you can reinstall or recover later. Keep them, and your recovery information, safe.

## Network and HTTPS

If DSM's firewall is on, allow the **DSM HTTPS port** (normally `5001`) from your trusted administrative network. Manager runs through that same DSM address at `/frameleaf-manager/`; its own connection port (normally `9443`) listens only on the NAS loopback interface and stays private. Once a library is installed, allow its application port (normally `2283`) from the networks your devices use. PostgreSQL needs no public port.

If the native window cannot connect:

1. Check that Package Center shows **Frameleaf Manager** and **Container Manager** as running.
2. Check that your browser trusts the DSM HTTPS certificate. Manager uses that same browser connection.
3. Open DSM with the **exact HTTPS hostname and port** you entered in the installer. A different hostname, an IP address or plain HTTP won't match.
4. Check the firewall rules for DSM HTTPS and, for an installed library, its application port. If the library itself cannot start, inspect its server and PostgreSQL logs in **Services**.

For access away from home, follow [Remote access](https://frameleaf.app/docs/cloud/remote-access/) or [Reverse proxy](https://frameleaf.app/docs/admin/reverse-proxy/). Keep Manager administration private.

## Existing manual Container Manager installations

If you run a manual **Container Manager → Project** deployment, keep using its release files, paths and credentials, and follow [Manual Docker Compose installation](https://frameleaf.app/docs/start/manual-install/) and [Upgrading](https://frameleaf.app/docs/admin/upgrading/#with-docker-compose) for it.

The native app is the Package Center way to install. Each database belongs to one installation: either the app or a manual project, never both.
