Skip to content

First steps after installing

Set up your server: the first run, step by step Watch on YouTube

After Manager setup or manual installation, open the photo application. This page takes you from an empty server to a library your whole household uses, with backups in place.

1. Set up the server and create the admin account

Section titled “1. Set up the server and create the admin account”
  1. From a computer on your home network, open http://<server-ip>:2283, or use the address Manager shows on its Overview.
  2. A new server opens straight on setup. Your progress is saved as you go, so you can come back to it.
  3. Follow the chapters: Welcome, Account, Library, Protection and Ready. The line above each page shows where you are, such as Account · 2 of 5.

Bringing a library back instead? The welcome page also offers Restore from a backup. See Restore on a fresh installation.

You can also set up a new server from the iPhone or Android app: on the same Wi-Fi, it finds the server and offers Set up.

Only the admin account and a writable library folder are required. Every other step starts on its Recommended choice, so you can simply choose Continue.

Choose your language.

Create the administrator for this server: enter your Name, Email and Password (twice). The password needs at least 8 characters. There’s no setup code to find. This account is always a local one, stored on the server, so you can sign in to your own server even when Frameleaf Cloud can’t be reached.

The first account is the administrator, who can add everyone else.

This step is optional. Linking the server to a Frameleaf account lets you reach your library away from home without port forwarding, sign in anywhere and add Cloud backup when you want it. Your photos still live on this server.

Choice What happens
Create account and link Your name and email come from the admin account. Choose a password of at least 8 characters, enter the 6-digit code Frameleaf emails you, and the server is linked straight away.
I already have a Frameleaf account Enter its email and password, and the code from your authenticator app if you use one, then choose Sign in and link.
Skip for now Carry on with the local admin. You can link a Frameleaf account later from Settings.

If the server can’t reach Frameleaf Cloud yet, or the account can’t link right now, setup says why in plain words and you can skip and link later. See Your Frameleaf account.

If your Frameleaf account already has a Cloud backup from another server, setup says We found a backup. Choose Restore this backup to bring the whole library back once setup is finished, or Start fresh to leave the backup untouched and begin with an empty library.

A Server licence gives your server its Frameleaf direct address. The relay for remote access and Cloud Backup come with a Frameleaf Cloud plan, and Cloud GPU uses wallet credit that you approve job by job. Your local administrator and library always work on their own.

Under Your photos are kept in, setup shows the folder and checks that it’s writable and how much space is free. It was chosen when Frameleaf was installed and can’t be changed here. Manager installations use the folder you chose in Manager, and you can move it later. Manual installations use UPLOAD_LOCATION in .env; change it only with a plan for the existing files and recreate the containers.

Choose a Folder layout for your originals:

Layout Pattern
Year / Month / file (recommended) {{y}}/{{MM}}/{{filename}}
Year / Date / file {{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}
Album / Year / file {{album}}/{{y}}/{{filename}}
Camera / Year / file {{make}} {{model}}/{{y}}/{{filename}}

This sets the storage template, which you can change later. See Choose a folder layout below.

Setup shows the hardware it Detected on this server, such as a GPU for search and faces, or for video and Studio. Then choose a Model tier for smart search, captions and faces:

Tier Best for
Light Fastest. Good search and faces on any processor.
Balanced (recommended) Sharper search, captions and faces. Fits most GPUs.
Best Highest quality. About twice as slow.

And choose Where processing runs: Local only, where everything runs on your server and nothing leaves your network, or Frameleaf Cloud GPUs, where heavy jobs run on fast rented GPUs and you confirm each one and its price first. See Workers and where jobs run and Cloud GPU.

Nightly database backups are on by default: every night at 2:00 AM, keeping 14. They protect your albums, people and edits. Leave them on unless another tool backs up the database.

If you’ve linked a Frameleaf account, you can also turn on Cloud backup for an encrypted, off-site copy of your originals.

Setting What it does
Map tiles Loads map images so photos can be shown on the map. The tile server sees which areas you view.
Check for Frameleaf updates Asks GitHub once a day whether a new Frameleaf release is out. Nothing about your library is sent.

Other outside calls that Frameleaf doesn’t need stay off.

Setup tells you where to find the Google Photos and iCloud Photos imports later. Nothing starts during setup. See Import from Google Photos and Import from iCloud Photos.

Check the summary and choose Open Frameleaf. Background work, such as indexing photos as they arrive, starts when you finish setup, not before.

When Frameleaf finds a library that’s already there, for example after an import with Manager, setup is shorter and changes nothing by itself:

  1. Sign in to finish setting up asks for your existing admin email and password. There’s nothing to register, and everyone else can keep using the library while you finish.
  2. Your library is safe shows your items, albums and people. Every original, album, face and edit is exactly where it was.
  3. On Your account, choose Keep your local admin or Link a Frameleaf account.
  4. Library check takes a quick look at the file records and points you to Library Care if any originals are missing or damaged. The full check runs in the background after setup.
  5. On Processing, you can Keep current model, so nothing is re-indexed, or choose a new tier and where the re-indexing runs: On this server, Frameleaf Cloud GPUs or Decide later.
  6. Your people shows what everyone else gets: a short Set up your account page the next time they sign in, which they can finish in any order or skip.

Keep the old installation stopped while Frameleaf uses the library. See Bring an existing library.

In the web app, click Upload and choose a few photos, or drag them onto the page. They appear in your timeline straight away and are processed in the background.

To watch the processing, select Settings in the sidebar to open the Command Center, then open Computers & background work and choose Background work.

Give each person their own account, so each has a private library, their own phone backup and their own faces and memories.

  1. Open Settings, then Users.
  2. Choose Add a person.
  3. Enter their Name and Email.
  4. Optionally set Role to Administrator, or choose their Space for this person (No limit by default).
  5. Choose How they first sign in. With A temporary password, Frameleaf makes one up and shows it to you once, to pass on; they change it the first time they sign in.
  6. Choose Add person.

The next time they sign in, they see a short Set up your account page: profile, appearance, the mobile app, privacy and notifications, and linking their Frameleaf account. They can do it in any order or skip it, and reopen it later from the account menu, then Set up your account.

When your server is linked to Frameleaf Cloud, you can instead invite people with their Frameleaf account. See Users and Share a server with people.

To share photos between accounts, use partners, shared albums and shared spaces. If family members upload the same files, physical deduplication stores them only once.

Install Frameleaf from the App Store or Google Play. You can also use http://<server-ip>:2283 in your phone’s browser. See iPhone and Android apps.

Connect the app:

  1. Install Frameleaf on your phone.
  2. Sign in with your Frameleaf account, choose the server the app finds on your Wi-Fi, or type the server address, such as http://192.168.1.20:2283. Then sign in with your email and password.
  3. Turn on backup and choose which albums to back up. The first backup can take a while on a large camera roll, so you may want to start with a few albums.

Each person’s Set up your account page shows a QR code that opens your server on their phone. For the details, see iPhone and iPad and Android.

By default, Frameleaf names stored files with a random identifier so names never clash. The storage template gives your originals readable folders and file names instead, such as 2024/07/IMG_1234.HEIC. The layout you picked during setup is a storage template.

To change it, go to Settings, then Storage & originals, then Folder layout:

  1. Turn on Sort originals into folders.
  2. Pick one of the four layouts, such as By year, then day (recommended), or Custom… to write your own pattern under Advanced: custom pattern. The preview sentence shows where a sample photo goes.
  3. Select Review changes, then Save changes.

A few things to know:

  • A new template only applies to new uploads. To move existing files into the new layout, select Re-file existing photos…, or start Sort originals into folders in Settings, then Computers & background work, then Background work. On a large library it can take hours.
  • If two files end up with the same name, a sequence number is added, so nothing is overwritten.
  • Copies are checked before the old file is removed, every time. A move never replaces another file, and one that was interrupted finishes on the next run. See How files are moved.
  • Dates and times use the server’s time zone (TZ).
  • {{album}} uses the most recently created album an item is in. To give items without an album their own folder, use a condition:
{{y}}/{{#if album}}{{album}}{{else}}Other{{/if}}/{{MM}}/{{filename}}
  • Special characters in variables are written as HTML entities (& becomes &amp;). Wrap the variable in three braces, such as {{{album}}}, to prevent that.

See Storage template for every variable and option.

Frameleaf backs up its database for you every night, but it doesn’t back up your photo files. You need both to restore.

Read Backup and restore for which folders matter and how to restore. For an off-site copy you don’t have to manage, see Cloud backup or Buddy backup.