Deploy and Host Shelf on Railway

Shelf (shelf.nu) is open-source asset management. Teams track equipment and inventory with photos, custom fields, categories, tags and locations, print QR codes that open an asset's page when scanned, record who has what with custody, and reserve items with bookings and a calendar. Workspaces keep each team's inventory separate. This is a community-maintained template; it is not affiliated with Shelf Asset Management Inc.

About Hosting Shelf

Shelf is a React Router app on Node with a PostgreSQL database, using Supabase for sign-in and file storage. Upstream's self-hosting guides expect a Supabase Cloud project configured by hand: migrations run by the operator, four storage buckets created in the dashboard, e-mail templates rewritten to send one-time codes, and the code length changed.

This template runs everything on Railway instead, in one project: a self-hosted Supabase (Postgres, Auth, Storage and the Kong gateway) and Shelf's official image, five services with every secret generated and no Supabase account. The first start applies Shelf's migrations, creates the buckets with the visibility Shelf's guide specifies, configures sign-up e-mails with 6-digit codes, and creates your owner account with a personal workspace through Shelf's own sign-up code, so you can sign in straight away.

Sign-up is closed by default and enforced in the database: the owner, the addresses or domains you list, and people invited to a workspace get accounts; nobody else. Premium plans belong to Shelf's hosted service, so every feature is on.

Why Deploy Shelf on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Shelf on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Concretely, this template keeps the database, authentication and storage services on Railway's private network, exposes Shelf and the gateway that serves signed photo URLs over HTTPS, and attaches volumes to the database and the file store.

Common Use Cases

Track a company's equipment, tools and devices with photos, locations and QR labels.
Lend and reserve gear with custody records and bookings: film and photo studios, schools, labs, rental shops.
Keep an audit trail of who had which asset and when.
Separate inventories per team or site with workspaces and invited members.

Dependencies for Shelf Hosting

An SMTP server for invitations, sign-in codes and password resets (any provider: Postmark, SendGrid, Mailgun, Amazon SES, your own). The deploy form asks for its host and sender address.
Optional: a free MapTiler key for location maps.
Nothing else. No Supabase account.

Deployment Dependencies

Shelf: https://github.com/Shelf-nu/shelf.nu (AGPL-3.0)
Supabase self-hosting stack: https://github.com/supabase/supabase/tree/master/docker (Apache-2.0)
MapTiler: https://www.maptiler.com
Template repository, images and tests: https://github.com/youssefsiam38/shelf-railway

Implementation Details

Shelf runs from its official image, pinned to a release, with a thin start-up wrapper and no code changes. Three wrappers adapt Supabase to Railway: init scripts and gateway config baked in, API keys minted from the shared JWT secret with byte-identical output in Node and Perl, e-mail templates served by the gateway, and the Vault key kept on the database volume. Every service refuses to start on missing, short or published example secrets. The bundle is tested as a whole in CI and on a live Railway deployment, including the owner's first sign-in, a code-based sign-up, a workspace invitation accepted by e-mail and an asset photo served through a signed URL.

The deploy form asks for OWNER_EMAIL, SMTP_HOST and SMTP_FROM_ADDRESS. After deploying, copy OWNER_PASSWORD from the app service's variables and sign in on the app's domain.