Skip to content
Gantry docs home
Gantry on GitHub,

Quickstart

Go from an empty folder to a running web service and database in about five minutes, then change code and watch it reload.

Getting startedUpdated 30 Sep 20265 min read

Before you start

  • Gantry 2.8 or later. Install it if gantry --version comes back empty.
  • A project with a lockfile. Any of npm, pnpm, bun, yarn, Cargo, Go modules or Poetry will do.
  • Ports 3000 and 5432 free on your machine.

  1. Create a project

    Run gantry init in the project root. It finds your lockfile, guesses the services and writes a gantry.toml short enough to read top to bottom.

    $ cd ~/code/acme-web$ gantry init  found    pnpm-lock.yaml · 412 packages  found    Dockerfile.db  wrote    gantry.toml · 2 services  wrote    .gitignore · added .env.local
    gantry.toml
    [project]name = "acme-web" [service.web]build = "lockfile"command = ["pnpm", "dev"]ports = ["3000"]depends_on = ["db"] [service.db]build = "Dockerfile.db"ports = ["5432"]volumes = ["db-data:/var/lib/postgresql/data"]

    The two lit lines are the ones that matter most: build = "lockfile" tells Gantry to build web without a Dockerfile, and depends_on holds web back until the database is healthy.

  2. Start your services

    $ gantry up  resolve  pnpm-lock.yaml · 412 packages           0.21s  layers   base, deps pulled · src built           48.6s  start    db   -> postgres://localhost:5432        41ms  start    web  -> http://localhost:3000            38ms  ready    2 services healthy · watching src/

    Open http://localhost:3000. The first run pulls base layers, about 180 MB for this project, which is most of those 48 seconds. Every run after that reuses them.

    Get your terminal back
    Add -d to start in the background, then follow one service with gantry logs -f web.

  3. Edit and reload

    Change any file under src/ and save. Gantry rebuilds only the source layer and restarts web; the database keeps running and keeps its data.

      change   src/app/page.tsx  layers   1 rebuilt (src)                         0.42s  restart  web -> healthy                          0.31s

    Editing the lockfile rebuilds the dependency layer as well, which takes longer the first time and is cached from then on.

  4. Shut it down

    Press Ctrl+C in the terminal running gantry up. Services stop in reverse dependency order and named volumes are kept, so your data is there next time.

    # remove containers and named volumes$ gantry down --volumes
    --volumes deletes your local database
    It removes every named volume in the project, including db-data. Dump anything you want to keep first with gantry exec db pg_dump app.

Next steps