Deploy Hatamoto on Railway
By the end you have Hatamoto running on Railway with its own PostgreSQL database, HTTPS on a Railway address, and an owner account you created from the deploy log. Railway runs containers for you, so there is no server to rent, update or log in to. The Hatamoto template sets up both services, their storage and every required setting, so the first deploy is one click.
The template lives at railway.com/deploy/hatamoto. Railway lists it as a verified template.
What it costs
Railway charges a plan fee that already includes some usage, then bills memory, CPU and storage by the second. A small Hatamoto site fits the Hobby plan; how much of the included usage it takes depends on your traffic, so check the project's usage page after the first week.
| Item | Price |
|---|---|
| Hobby plan, always on, 5 GB volumes, 2 custom domains per service | $5 a month, which includes $5 of usage |
| Memory | $10 per GB a month, billed per second |
| CPU | $20 per vCPU a month, billed per second |
| Volume storage, including volume backups | $0.15 per GB a month |
| Outbound traffic | $0.05 per GB |
| Free trial for new accounts | $0, with a one-time $5 credit for 30 days |
Prices as of 19 November 2026, from Railway's pricing. They change, so check the provider before you order.
Before you start
- A Railway account, from railway.com. The trial needs no card; the Hobby plan, which a site you keep needs, does.
- A domain name, if you want the site on your own address. Its DNS host must let you add a
CNAMEand aTXTrecord. Without one, the site runs on a freeup.railway.appaddress. - The details of an email service (SMTP), so Hatamoto can send password resets and invitations. You can add them now or later.
- An SSH key registered with Railway, only if you want a shell in the container with
railway ssh. The CLI offers to register one the first time.
Step 1: Open the template
Click Deploy on Railway above, or open railway.com/deploy/hatamoto and click Deploy Now. Sign in, or create your Railway account. The page lists the two services the template creates: Postgres, the database that holds every page, post and setting, and hatamoto, the site, the admin and the API in one program.
Step 2: Check the variables and deploy
Railway shows the variables of each service before it deploys. Every required one already has a value, so you can click Deploy as it is. Each variable is a named setting Railway passes to Hatamoto when it starts:
| Variable | Value in the template | What it does |
|---|---|---|
DATABASE_URL | ${{Postgres.DATABASE_URL}} | Where the database is, filled in from the Postgres service. Leave it. |
PORT | 8080 | The port Railway sends traffic to and checks for health. |
API_PORT | ${{PORT}} | The port Hatamoto listens on. Must equal PORT. |
API_HOST | 0.0.0.0 | Listen on every address, so Railway's proxy can reach the site. |
ENVIRONMENT | production | Secure admin cookies, HSTS and JSON logs. |
PUBLIC_BASE_URL | https://${{RAILWAY_PUBLIC_DOMAIN}} | The site's public address, used in links, sitemaps and emails. Change it when you add your domain. |
MEDIA_UPLOAD_DIR | /data/uploads | Uploaded files, kept on the /data volume. |
RAILWAY_RUN_UID | 0 | Runs the container as root so it can write to the volume. |
HATAMOTO_TRUSTED_PROXIES | Railway's private address ranges | Lets Hatamoto read each visitor's real address through Railway's proxy. |
SMTP_HOST, SMTP_PORT | empty, 587 | Optional. Your email server and its port. |
SMTP_USERNAME, SMTP_PASSWORD | empty | Optional. The email account's login, or an API key as the password. |
SMTP_FROM, SMTP_FROM_NAME | empty | Optional. The sender address and name on outgoing mail. |
Two more you may add: HATAMOTO_TRUSTED_CDN=cloudflare if your domain runs through Cloudflare, and HATAMOTO_SETUP_CODE with at least 12 letters or digits to choose your own setup code. The full list is in the Configuration reference.
Step 3: Wait for the first deployment
Railway opens the new project and starts Postgres, then hatamoto. On its first start Hatamoto creates its tables, generates its server secret and saves it on the /data volume. Railway asks /health until it answers, then marks the deployment Active. It allows 300 seconds by default, which is plenty for a first start.
Step 4: Find the setup link in the deploy log
Your admin is at a private address made for your install, not at /admin. Click the hatamoto service, open Deployments, then the logs of the active deployment, and search for Setup. The line looks like this:
Setup: open https://example.up.railway.app/k7qm-x2rf-9tdc/setup and enter code K7M2-RT9PThe setup code is printed only in the log, so only someone with access to your Railway project can create the first owner.
Step 5: Create the owner account
Open the link, enter the code and create your owner account. The wizard then asks for the site name and email settings; First run explains each screen. Bookmark the admin address, which is the link without /setup. If you lose it, run railway ssh -- hatamoto admin-url from a terminal linked to the project.
Step 6: Add your own domain
On the hatamoto service, open Settings, find Public Networking and click + Custom Domain. Type the domain and pick port 8080 if Railway asks. Railway shows a CNAME record and a TXT record: add both at your DNS host. When the green check appears, open Variables, set PUBLIC_BASE_URL to https:// and your domain, for example https://example.com, and click Deploy on the staged change. Railway issues the HTTPS certificate itself. The trial allows one custom domain and Hobby two per service, and example.com and www.example.com count as two.
Step 7: Set up email
Hatamoto sends password resets and invitations by email. Fill in the SMTP_ variables on the hatamoto service and deploy the change, or enter the same details in the admin under Settings > Email. Email covers both and how to send a test message.
Step 8: Turn on backups
Your content lives in the Postgres service and your uploads and server secret on hatamoto's /data volume, so back up both. Open each service's Backups tab and choose a schedule: Daily keeps 6 days, Weekly 27 days and Monthly 89 days. Railway restores a backup into the same project only, so for a copy elsewhere also set up the off-site copy in the admin under Settings > Backups & recovery. See Backups.
Check it worked
The hatamoto service shows its latest deployment as Active, and Railway only switches to a deployment after /health answers. From your own computer, run:
curl -i https://example.up.railway.app/healthwith your own address. The first line of the answer ends in 200. Then open the address in a browser: you should see a padlock and the starter home page, and you can sign in at your admin address.
If something goes wrong
- If the deployment fails its health check, read the deploy log. A line about
DATABASE_URLmeans Postgres is not running or the variable was changed; set it back to${{Postgres.DATABASE_URL}}and deploy. - If your custom domain answers 404, the
TXTrecord is missing or not live yet. Railway routes the domain only after both records verify, and DNS changes can take up to 72 hours. - If links, sitemaps or emails still show the
up.railway.appaddress,PUBLIC_BASE_URLwas not changed or the staged change was not deployed. - If the setup line has scrolled out of the log, add
HATAMOTO_SETUP_CODEwith a code of your own, deploy, and use that code with the setup link. The log then reminds you to use the variable instead of printing a code. - If uploads or the server secret fail with a permission error, check that
RAILWAY_RUN_UIDis0and thatMEDIA_UPLOAD_DIRpoints inside/data.
Use the command line instead
Railway's CLI deploys the same template. Install it with brew install railway or npm i -g @railway/cli, then sign in, create an empty project and add the template:
railway login
railway init
railway deploy --template hatamotoThis sequence is composed from the Railway CLI reference and has not been run for this page. Add --variable "hatamoto.SMTP_HOST=smtp.example.com" to set a variable on the way in. railway logs then shows the deploy log with the setup line, and railway domain example.com adds your domain.
FAQ
How much does it cost to run Hatamoto on Railway?
The Hobby plan is $5 a month and includes $5 of usage. If the site and its database use more, you pay the usage total instead, at the rates in the table above. Hatamoto itself is free. We have not measured a typical bill, so watch the usage page for the first week.
Can I use Railway's Free plan?
It is not a good fit. Free services get 0.5 GB of RAM and sleep when idle, there are no custom domains, and Railway says the monthly $1 covers about 100 MB of RAM around the clock. A site you want to stay up needs Hobby.
What happens when the trial ends?
Railway stops the services after 30 days or when the $5 credit is spent. Upgrade to Hobby and redeploy to carry on. On the trial, volume data is deleted 30 days after it expires.
Where is my content stored?
Pages, posts, settings, themes and plugins are in the Postgres service, on its own volume. Uploaded files, the server secret and Hatamoto's downloaded updates are on the hatamoto service's /data volume.
Do I need to redeploy to update Hatamoto?
No. Hatamoto checks for new releases itself, installs signed updates onto the /data volume, and goes back to the previous version if an update fails its health check. See How updates work.
Can I run more than one copy of the site?
Not with this template. Railway does not allow replicas on a service with a volume, and Hatamoto keeps its uploads and secret on one. For several copies behind a load balancer, see Multiple replicas and health checks.
How do I get a shell in the container?
Install the Railway CLI, run railway link in an empty folder to pick the project, then railway ssh. Every Hatamoto command works there, for example hatamoto version.
To run Hatamoto on a server of your own instead, see DigitalOcean, Vultr, Amazon Lightsail, Amazon EC2, Hetzner Cloud and Linode. The same steps are in Deploy Hatamoto on Railway in the docs.