Skip to content
Frameleaf Docs

First steps after installing

Your containers are running. 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.
  2. Click Getting Started. A short setup opens. Your progress is saved as you go, so you can come back to it.
  3. Follow the chapters: Welcome, Account, Library, Protection and Ready.

Only the admin account and a writable library folder are required. Every other step has a recommended choice you can keep with Use recommended.

Welcome

Section titled “Welcome”

Choose your language.

How you’ll sign in

Section titled “How you’ll sign in”
Choice What it means
Frameleaf account (recommended) Sign in anywhere with one account, reach your library away from home without port forwarding, and use cloud backup and faster processing when you want them. Your photos still live on this server. You create the local administrator first, then approve the server in your Frameleaf account.
Local account only You create the admin with a name, email and password, stored only on this server. Nothing leaves your network. You can link a Frameleaf account later from Settings.

If the server can’t reach Frameleaf Cloud, or Frameleaf Cloud isn’t set up on it, setup offers the local account and you can link later. See Your Frameleaf account.

Your account

Section titled “Your account”

Enter your Name, Email, Password (twice) and the Setup code.

The setup code is 8 letters and numbers, shown as XXXX-XXXX. It’s printed on the server’s console and in its log when it starts:

Terminal window
docker logs frameleaf_server

or, to print only the code:

Terminal window
docker exec -it frameleaf_server frameleaf-admin setup-code

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

Where your library lives

Section titled “Where your library lives”

Setup shows your Storage location (the UPLOAD_LOCATION you set in .env) and checks that it’s writable and how much space is free. To change it, edit .env where Frameleaf is installed and come back.

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.

Processing

Section titled “Processing”

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, when available, Frameleaf Cloud GPUs, where heavy jobs can use rented GPUs and you confirm each one and its price first. See Workers and where jobs run and Cloud GPU.

Protection

Section titled “Protection”

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.

Privacy

Section titled “Privacy”
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 Checks whether a new Frameleaf release is out. Nothing about your library is sent.

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

Bring everything together

Section titled “Bring everything together”

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.

You’re ready

Section titled “You’re ready”

Check the summary and choose Open Frameleaf.

2. Try an upload

Section titled “2. Try an upload”

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 Compute & jobs.

3. Add the people you live with

Section titled “3. Add the people you live with”

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 Create user.
  3. Enter their Email, a Password (twice) and their Name.
  4. Optionally set a Quota Size (GiB) (leave it empty for unlimited), turn on Require user to change password on first login, or make them an Admin User.
  5. Choose Create.

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.

4. Connect your phone

Section titled “4. Connect your phone”

When the apps are available:

  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.

5. Choose a folder layout

Section titled “5. Choose a folder layout”

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 Administration, then Settings, then Storage Template:

  1. Turn on Enable storage template engine. Leave hash verification on unless you’re sure.
  2. Choose a preset, or type your own template with the variables listed on the page. The preview shows the path for a sample photo.
  3. Select Save.

A few things to know:

  • A new template only applies to new uploads. To move existing files into the new layout, run the Storage Template Migration job from the jobs page. 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.
  • 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.

6. Protect your library

Section titled “6. Protect your library”

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.

Optional next steps

Section titled “Optional next steps”