Skip to main content

Startup Guide

This guide walks you through launching a self-hosted Trellilume library and connecting the apps.

1. Choose your host​

Trellilume runs well on a small server, NAS, or always-on desktop. Make sure you have enough storage for your photo library and backups.

2. Install the backend​

Use Docker or a direct install to run the FastAPI service.

  • Set a secure NESTPICS_SECRET_KEY.
  • Point NESTPICS_UPLOAD_ROOT to the folder where photos live.
  • Configure SMTP so account verification and password reset messages can be delivered. At minimum, set NESTPICS_SMTP_HOST and NESTPICS_SMTP_FROM_EMAIL, then use the port, username, password, and security mode supplied by your email provider. A typical STARTTLS setup uses NESTPICS_SMTP_PORT=587 and NESTPICS_SMTP_SECURITY=starttls.
  • Start the API and confirm it is reachable on your network.

3. Connect the apps​

On iOS, Android, or web, enter your server URL (for example http://192.168.1.10:8000) and sign in.

If the selected server requires email verification, enter the verification token it sends before signing in. Server operators must configure SMTP before enabling that requirement. For local testing without SMTP, set NESTPICS_EMAIL_DEBUG_TOKENS=1; never enable debug tokens on an internet-accessible server.

Optional: Access outside your LAN​

Want to use Trellilume away from home or share links publicly? Follow the Remote Access guide to set up a public URL.

4. Import your library​

Choose the folders you want Trellilume to index. Let the initial scan complete, then start browsing and creating albums.

5. Invite family​

Create a shared space and invite family members. Assign roles that match how you want them to contribute.

6. Set up backups​

Keep originals protected with a secondary drive or sync job. Trellilume is built for local-first workflows, so your storage strategy stays in your control.

7. Review storage policy​

The Server Owner can open Settings > Server > Storage & limits to review logical usage, capacity health, optional product quotas, and operational safeguards. Ordinary self-hosted servers begin with product quotas set to Unlimited and the policy in Observe mode.

Read Storage Policies & Limits before enabling Enforce on a populated server. Observe and Enforce affect product quotas; finite file-size, concurrency, reservation, and low-disk safeguards remain active in both modes.

Next steps​