Getting started
First project and worktree
Register a repository on a box, branch a worktree off it, and open its dev server.
Add the repository
Shipyard works with repositories that are already on the box. Register one as a location, a name for a directory on that box:
berth location add my-box/app ~/work/app
berth locations my-boxA path under your laptop's home is sent as ~/…, so the box reads it against
its own home. A location can be any directory, but worktrees need a git
repository. If the repository isn't on the box yet, clone it there first
(an SSH command starts in your home on the box, so work/app is
~/work/app):
ssh me@my-box git clone https://github.com/you/app work/appIn the app, Add a project takes a path on the box, a git URL or
owner/repo to clone, or a new name to create an empty repository, and says
what Enter will do before you press it. One repository checked out on several
boxes is one project in the sidebar; see
projects and worktrees.
Make a worktree
berth worktree new my-box/app/fix-loginShipyard runs git worktree add next to the repository, as ~/work/app-fix-login,
on a branch named fix-login (or --branch B, from --base REF). An
existing branch, locally or on origin, is checked out as it is. Then:
- a
worktree.createdevent goes to anything listening; - the repository's setup script runs in the new worktree, in the background, with its output in a log;
- once setup succeeds, the worktree's services marked
autostartstart.
Worktrees made by any other tool, including plain git worktree add, show up
too: berthd watches its locations.
Give it its own ports and setup
Every worktree gets a block of ports of its own ($BERTH_PORT,
$BERTH_PORT_1, …) and a set of BERTH_* variables. A repository says how
to use them in .berth/config.json:
{
"setup": "pnpm install",
"ports": 2,
"env": { "DATABASE_URL": "postgres://localhost/$BERTH_WORKTREE_SLUG" },
"services": [{ "name": "web", "run": "pnpm dev --port $BERTH_PORT", "autostart": true }]
}Commit it, then trust it once on each box: the file runs commands, so a
box runs none of it (only ports) until someone trusts it there, and again
after it changes. The app asks (This repository wants to run …), or run
berth location config my-box/app and then --trust HASH with the hash it
prints; see
trusting a repository's config.
Every box that trusts it then does the same thing. For setup you'd rather not
commit, use a kit or the box's own config
(project config).
Open it
A worktree's dev server is at a private URL on your laptop, served by the laptop agent's proxy through the box connection, with nothing exposed on the box:
http://fix-login.app.my-box.localhost:1377/ the worktree's own port
http://3000.my-box.localhost:1377/ any port on the boxberth open my-box 3000 # open a port in your browser
berth service list my-box/app/fix-login # the worktree's services
berth edit my-box/app/fix-login # open it in your editor, over SSHIn the app, the worktree's workspace has terminals, splits and browser tabs onto those URLs; the Run menu starts and opens its services. Drag a tab onto a pane's edge to split it there, or a pane by its header onto the tab strip to make it a tab again; a tab's right-click menu has Split right and Split down too.