# Run your own Frame server

> Host Frame for you and your friends: one small open-source program and one data folder. What you need, which setup to pick, and where everything is documented.

Source: https://crow.sg/apps/frame/docs/

Frame keeps your group's photos on a server you control: a small virtual server, a Raspberry Pi at home or an old laptop. The server is one small open-source program, `frame-server`, with one data folder and no outside services to sign up for. If you can copy commands into a terminal and edit a text file, you can run it.

The server is open source under AGPL-3.0, on [GitHub](https://github.com/Crow-Tech-Pte-Ltd/frame). The iOS and Android apps are published by Crow Tech and connect to any Frame server: everyone types your server's address when they sign up.

## What you need

- **A Linux machine that stays on.** A small virtual server, a home computer or a Raspberry Pi 3B+, 4, 5 or Zero 2 W. One CPU core and 512 MB to 1 GB of RAM are enough; Frame itself uses about 30–60 MB.
- **Some disk.** Ten friends sending five photos a day need about 8 GB a year. Videos need more. Media can also go to an S3-compatible bucket such as Cloudflare R2 ([Storage & sizing](https://crow.sg/apps/frame/docs/storage/)).
- **A domain name**, such as `frame.example.com`. The apps need HTTPS, and HTTPS needs a name. A subdomain of a domain you already own works and costs nothing extra.
- **Docker with Compose** on an amd64 or arm64 machine (on a Raspberry Pi, a 64-bit OS), or **systemd** on an amd64, arm64 or armv7 machine for the Linux installer.

## Pick a setup

| You have… | Use | HTTPS by |
|---|---|---|
| A small VPS and a domain, nothing else yet | [Linux installer with built-in HTTPS](https://crow.sg/apps/frame/docs/install-systemd/#vps) (also the [quickstart](https://crow.sg/apps/frame/docs/quickstart/)) | Frame itself (Let's Encrypt) |
| A Raspberry Pi or home computer, and no open ports (or CGNAT) | [Cloudflare Tunnel with the installer](https://crow.sg/apps/frame/docs/install-systemd/#cloudflare-tunnel) or [with Docker](https://crow.sg/apps/frame/docs/install-docker/#cloudflare-tunnel) | Cloudflare |
| A server where you already use Docker | [Docker Compose with Caddy](https://crow.sg/apps/frame/docs/install-docker/#caddy) | Caddy, automatically |
| A server that already runs Caddy, nginx or another web server | [Behind your own proxy](https://crow.sg/apps/frame/docs/install-systemd/#reverse-proxy) | your proxy |

Whichever you pick, you end up with an address like `frame.example.com` that you and your friends type into the Frame app.

> [!NOTE] Always set `FRAME_PUBLIC_URL`
> Set it to the address people type into the app, such as `FRAME_PUBLIC_URL=https://frame.example.com`. Sign in with Apple and Google only work when it is set, because each sign-in is bound to your server's name: that stops another Frame server from reusing a login token to sign in as you on yours. Frame also uses it in invite links. Every setup in these docs sets it. Reached under several names, say a public domain and a LAN name? List them all, separated by commas, with the main one first.

## How it fits together

- **The apps** talk to your server over HTTPS. New servers are invite-only: on its first start the server prints a one-time link to create your admin account, and you invite friends from the admin panel or the app.
- **The server** stores accounts, friendships, messages and moments in SQLite, and the photos and videos on its own disk or in an R2 bucket. It never decodes or re-encodes media, so even a Pi stays idle most of the time.
- **The admin panel** at `/admin` manages users, reports, invites and settings. It never shows anyone's photos or messages, except a single item a member reports to you. Admins can also manage the server from the apps.
- **Notifications** go through Crow Tech's content-blind relay at `frame.crow.sg`, because Apple and Google only deliver notifications signed with the app publisher's keys. The content is end-to-end encrypted between your server and each phone, and you can turn push off.

## Get the apps

The apps are free, with no ads, and work with any Frame server.

- **iPhone:** [Download on the App Store](https://apps.apple.com/app/id6832514449)
- **Android:** Coming soon to Google Play
- **Server:** [Free and open source · GitHub](https://github.com/Crow-Tech-Pte-Ltd/frame)

## Where to go next

- [Quickstart](https://crow.sg/apps/frame/docs/quickstart/): A small server with your own domain, from nothing to your first invite.
- [Set up with an AI agent](https://crow.sg/apps/frame/docs/ai-setup/): A ready-to-paste prompt that lets a coding agent set the server up with you.
- [Docker Compose](https://crow.sg/apps/frame/docs/install-docker/): The official image behind Caddy, a Cloudflare Tunnel or your own proxy.
- [Linux installer (systemd)](https://crow.sg/apps/frame/docs/install-systemd/): Built-in HTTPS on a VPS, a Pi behind a tunnel, or behind Caddy or nginx.
- [Binary & source](https://crow.sg/apps/frame/docs/install-binary/): Run the release binary yourself, build from source, or try it locally.
- [First run & admin account](https://crow.sg/apps/frame/docs/first-run/): The one-time setup link, your admin account and two-factor authentication.
- [Connect the apps & invite](https://crow.sg/apps/frame/docs/connect/): Point the apps at your server, and decide who can join.
- [Admin panel](https://crow.sg/apps/frame/docs/admin-panel/): Users, reports, invites and settings, on the web and in the apps.
- [Keep the admin panel private](https://crow.sg/apps/frame/docs/private-admin/): A local-only panel over SSH, local mode, or no panel at all.
- [Push notifications](https://crow.sg/apps/frame/docs/push/): How the content-blind relay delivers notifications, and how to turn it off.
- [Storage & sizing](https://crow.sg/apps/frame/docs/storage/): Local disk or Cloudflare R2, and how much disk, bandwidth and money.
- [Backups & restore](https://crow.sg/apps/frame/docs/backups/): What to back up, nightly backups, and restoring on a new machine.
- [Upgrading](https://crow.sg/apps/frame/docs/upgrading/): Updating a systemd or Docker install, and hearing about releases.
- [Configuration](https://crow.sg/apps/frame/docs/configuration/): Every frame.conf setting and the admin command line.
- [Security](https://crow.sg/apps/frame/docs/security/): What Frame protects, what it doesn't, and a checklist for your server.
- [Troubleshooting](https://crow.sg/apps/frame/docs/troubleshooting/): Fixes for connection, invite, HTTPS, upload and notification problems.

The repository has the same material in its own words: the [self-hosting guide](https://github.com/Crow-Tech-Pte-Ltd/frame/blob/main/docs/SELF-HOSTING.md), the [configuration reference](https://github.com/Crow-Tech-Pte-Ltd/frame/blob/main/docs/CONFIG.md), the [admin panel](https://github.com/Crow-Tech-Pte-Ltd/frame/blob/main/docs/ADMIN.md), the [security model](https://github.com/Crow-Tech-Pte-Ltd/frame/blob/main/docs/SECURITY.md) and the [push protocol](https://github.com/Crow-Tech-Pte-Ltd/frame/blob/main/docs/PUSH.md).

> [!WARNING] Your friends trust you with their photos
> Whoever runs a server can see what is stored on it. Keep the server updated and backed up, and only join servers run by people you trust.