Flightstead

Support

A good manual, not a managed server.

Flightstead is self-hosted software. The app and server come with documentation, but installing and operating your server remains your responsibility.

Before you begin

You should be comfortable with SSH, DNS records, environment variables, HTTPS, a long-running Node process, and backups—or have someone who can manage those for you.

Start with the right guide

Flightstead runs as one Node.js process with a SQLite database and local media storage. Choose the guide that matches your server:

General Linux guideNode.js, SQLite, Caddy or nginx, domains, and backups. Uberspace walkthroughShared hosting, supervisord, mail, domains, and TLS. Synology walkthroughContainer Manager, storage, reverse proxy, and upgrades. Source and issuesBrowse releases, documentation, and report reproducible bugs.

What support is available?

I maintain Flightstead and its setup documentation, and I welcome clear bug reports. I cannot install, configure, administer, or troubleshoot individual servers, hosting accounts, domains, DNS, reverse proxies, mail providers, firewalls, or backups.

That boundary keeps Flightstead sustainable and your infrastructure under your control. If server administration is unfamiliar, a technically experienced friend or a local hosting professional is the best person to help.

Common questions and gotchas

What do I need to run Flightstead?

A domain you control, an always-on Linux host or supported Synology, Node.js 22 or later, HTTPS through a reverse proxy, working outbound email, and the ability to SSH into the machine. The server itself uses SQLite, so there is no separate database service.

How do I connect the iPhone app?

Run npm run bootstrap-owner interactively on the server and scan the QR code with Scan to Connect in the app. The code is single-use and expires after 20 minutes. Re-run the command if it has expired. You can also enter your domain and sign in using an emailed code.

The app cannot connect to my server. What should I check?
  • api.yourdomain.com resolves to the correct host.
  • The API hostname has a valid HTTPS certificate.
  • Your reverse proxy sends both the API hostname and public-site hostname to the Flightstead process.
  • The process is running on the port configured in your environment.
  • If you entered only a domain in the app, remember that it assumes the api.<domain> convention.
My sign-in code never arrives.

Confirm that NODE_ENV=production, every SMTP_* value is correct, and your mail provider accepts the configured sender. ALLOWED_SIGNUP_EMAILS is required in production and must include the address you are using. On Uberspace, use the account hostname for SMTP_HOST, not localhost.

The QR code says it is invalid or expired.

Pairing codes last 20 minutes and work once. Run npm run bootstrap-owner again in an interactive terminal, then scan the new code. Automated deployments do not print a reusable pairing code.

My public site or custom domain does not load.

The setting in Flightstead does not change DNS or create a certificate. Point the hostname to your server, add it to Caddy, nginx, Uberspace, or your Synology reverse proxy, wait for HTTPS to become valid, and then set it as the canonical domain in the app.

Photographs fail to upload or render.

Check free disk space and confirm that LOCAL_STORAGE_DIR exists and is writable by the running service. Run npm install on the target server itself so the correct native sharp image-processing package is installed.

What should I do after pulling an update?

Run npm install, npm run build, npm run db:migrate, and npm run bootstrap-owner, then restart the process using your host's service manager. Read release notes before updating and keep a current backup.

What needs to be backed up?

Back up both the SQLite database named by DATABASE_URL and the media directory named by LOCAL_STORAGE_DIR. For a consistent copy, briefly stop the Flightstead process while taking the backup. Keep copies away from the server and test that you can restore them.

Can you set up or log into my server for me?

Sorry, no. I cannot take access to or responsibility for individual servers. The documentation is designed to be followed by the person operating the host; a server administrator can use the same guides if you prefer help.

Reporting an app or server bug

For a reproducible Flightstead bug, email service@adrianthomas.com or open a GitHub issue. Include the app or server version, the expected result, what happened instead, and steps to reproduce it.

Do not send passwords, authentication codes, private content, API keys, or unredacted logs. Hosting-specific administration remains outside the available support.