Getting started
Shipyard is a command-line tool. It runs on your machine, with your own provider accounts and your own keys. This website keeps your account, your stack choices and your licence. It never sees a provider key.
Install
Your personal install command is on your account page. Copy it into your terminal.
Where to type commands
Every command in these docs is typed into a terminal: a window where you type a line and press Enter.
- Windows. Press the Windows key, type
PowerShell, press Enter. - Mac. Press Cmd and Space, type
Terminal, press Enter.
To paste a command, copy it here, click in the terminal window, and press Ctrl+V (Cmd+V on a Mac), then Enter. When Shipyard asks for a token, what you paste stays invisible. That is on purpose: paste, then press Enter.
One thing to install first
Shipyard runs on Node.js, version 20 or newer. Type node -v in the terminal. If it prints a number of 20 or more, you have it. If it prints an error, download the LTS installer from nodejs.org, run it with the default answers, then close the terminal and open a new one.
Then paste your install command. Afterwards, type shipyard on its own at any time: it shows where you are and the next command to run.
Rehearse first
A dry run goes through all sixteen steps against fake providers. It needs no tokens and touches nothing: no network, no keychain, no accounts.
shipyard init demo --domain demo-harbor.dev \ --description "A demo project to rehearse a launch." shipyard apply demo --dry-run
Then for real
Five steps. Allow about an hour the first time; most of it is making tokens, which you do once.
1. Pick your stack
Choose your providers, or keep the defaults.
2. Connect your providers
shipyard setup
Opens a page in your browser, served from your own machine on 127.0.0.1, that walks through every provider in your stack: the one-time checklist, a link to the token page (prefilled for GitHub and Cloudflare), the permissions, and a box to paste the token into. Each token is tested and stored in your system keychain. The page never shows a stored token again and closes when you finish.
Prefer the terminal? The same thing, one provider at a time:
shipyard creds # lists the tokens your stack needs shipyard creds add github # repeat for each provider on the list shipyard creds test # every line must show a tick
Each creds add says where to create the token and which permissions to tick, then tests it. Tokens go into your system keychain. See Tokens.
Then go through the one-time setup at each provider. A launch stops at the step that needs one of these if it is missing, so do them now. This is the list for the default stack; shipyard plan prints the list for yours, with the same links.
- GitHub. If your repos live in an organisation: allow fine-grained tokens there (Organisation settings, Personal access tokens, Allow access via fine-grained personal access tokens). Without it the token cannot see the organisation.
- Railway. Add a payment method and choose the Hobby plan ($5 a month). A trial account cannot attach a custom domain. Open the page
- Railway. Install the Railway GitHub app on the account that owns your repos, with access to all repositories, so Railway can deploy from them. Open the page
- Cloudflare. Add a card and make it the default payment method. Open the page
- Cloudflare. To buy domains: on the Registrations page press Create default contact and fill in your name, address, email and phone. Write the phone as +country code, a dot, then the number without its leading 0, for example +31.612345678. Cloudflare may email a verification link to that address: click it. There is no separate agreement to accept after that. Do not buy a domain there and skip its Create Registrar API token button: Shipyard's token needs more permissions than that one has. Open the page
- Cloudflare. Switch R2 on once. It uses the card above; the first 10 GB are free. Open the page
- Resend. The free plan holds one domain. If you already have one there, remove it or move to a paid plan, or the new domain is refused. Open the page
- Stripe (test mode). Nothing for test mode. To take real payments later, finish Stripe's business verification; it can take a day or more, so start it now. Open the page
- Google (Analytics and Search Console). Create a Google Analytics account and accept its terms. Shipyard adds a property to it; it cannot create the account. Open the page
- Anthropic. Add credit. A key on an account without credit passes the check and then fails in your app. Open the page
3. Create the project
shipyard init yourproject --domain yourdomain.com --forward-to you@example.com
Add --own if you already own the domain (it must be on Cloudflare). Add --repo owner/name to launch a repository you already have: Shipyard reads it and never writes to it.
4. Rehearse and read the plan
shipyard apply yourproject --dry-run shipyard plan yourproject
The plan lists everything that will be created, every price, and the spend cap. Nothing has been touched yet.
5. Launch
shipyard apply yourproject
It stops and asks you to type buy before it buys the domain. Cloudflare emails you one link to confirm mail forwarding. The rest is waiting: a certificate can take ten minutes.
If a step fails, fix what it tells you and run shipyard apply again. It continues from that step and never creates a second copy of anything. shipyard summary yourproject shows what exists; shipyard check yourproject runs the health check again.
You already have a host project
Shipyard looks for a host project named after your Shipyard project, with a service called web, before it creates one. Rename yours to match and it is adopted: the database, domain and variables are added to it. Remove services you do not need first. Note that shipyard destroy would then delete that project too; it is on the list it shows you before you confirm.
Take payments
Every launch starts with Stripe in test mode. When Stripe has verified your business:
shipyard creds add stripe-live shipyard go-live yourproject
It asks first, then creates the same products, prices and webhook in live mode and swaps the keys on your host.