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”- From a computer on your home network, open
http://<server-ip>:2283, or use the address Manager shows on its Overview. - A new server opens straight on setup. Your progress is saved as you go, so you can come back to it.
- 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.
Welcome
Section titled “Welcome”Choose your language.
Your account
Section titled “Your account”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.
Add a Frameleaf account
Section titled “Add a Frameleaf account”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.
Where your library lives
Section titled “Where your library lives”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.
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 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.
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 | 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.
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. Background work, such as indexing photos as they arrive, starts when you finish setup, not before.
After an import
Section titled “After an import”When Frameleaf finds a library that’s already there, for example after an import with Manager, setup is shorter and changes nothing by itself:
- 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.
- Your library is safe shows your items, albums and people. Every original, album, face and edit is exactly where it was.
- On Your account, choose Keep your local admin or Link a Frameleaf account.
- 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.
- 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.
- 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.
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 Computers & background work and choose Background work.
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.
- Open Settings, then Users.
- Choose Add a person.
- Enter their Name and Email.
- Optionally set Role to Administrator, or choose their Space for this person (No limit by default).
- 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.
- 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.
4. Connect your phone
Section titled “4. Connect your phone”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:
- Install Frameleaf on your phone.
- 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. - 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 Settings, then Storage & originals, then Folder layout:
- Turn on Sort originals into folders.
- 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.
- 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&). 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”- Bring in an existing photo folder without copying it: External libraries.
- Import from Google Photos or iCloud Photos.
- Speed things up with a GPU: Hardware acceleration, or run machine learning on another computer: Remote machine learning.
- Turn on AI descriptions and smart albums: AI descriptions. Read the recommended setup order first.
- Reach your library away from home: Remote access or your own reverse proxy.
- Look around: the features overview lists everything Frameleaf can do.
© 2026 Frameleaf Inc. All rights reserved.
Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.
