Install and run

What you need

Gansey runs on Linux x86_64, Linux aarch64 and macOS. Release builds for macOS are for Apple silicon. You need:

• the gansey executable for your platform;
• Postgres 14 or later, reachable from the machine;
• pg_dump, pg_restore and tar on the PATH if you want backups. The Postgres client tools must match the server's major version.

The binary is self-contained: the admin, the bundled animation runtime and the database migrations are all inside it. Copy it somewhere on the PATH, or next to the site's files.

To build it from source instead, build the admin first so the binary has something to embed (pnpm install then pnpm run build in admin/), then run cargo build --release. The executable ends up at target/release/gansey.

Create the database

Create a database and a user that owns it:

createuser gansey --pwprompt
createdb gansey --owner gansey

First start

Make a folder for the site and run Gansey from it. Everything the site writes to disk (media, logs, backups, modules) goes under ./data/ relative to the working directory unless you configure otherwise.

mkdir example-site && cd example-site
DATABASE_URL=postgres://gansey:secret@localhost:5432/gansey gansey serve --migrate

--migrate applies any pending migrations before the server starts. You can leave it on: it does nothing when the database is up to date. Without it, a database that has never been migrated cannot load its site, and the log says so. To migrate without serving, run gansey migrate.

The server listens on http://127.0.0.1:8080 by default. Change that with --bind and --port, or in gansey.toml (see Configuration).

Create the owner account

Open http://127.0.0.1:8080/admin/. On a site with no users, the admin shows Set up your site instead of the sign-in screen. Enter your name, email and a password of at least 10 characters. That account becomes the site's administrator and you are signed straight in. The set-up screen only works while there are no users; after that everyone signs in normally.

If you would rather do this from a terminal, gansey user create --email [email protected] --name "Site owner" makes the first user an administrator too. See Users and sign-in.

Until a home page is published, / shows the built-in welcome page with a link to the admin.

Check the installation

gansey doctor checks what the site needs and prints one line per check:

gansey doctor

It reports on the database connection, how many migrations are applied, whether any users exist, the media folder, the log folder, pg_dump, pg_restore and tar, whether email is configured, and the public URL used in links. Any failed check is marked FAIL and the command exits with status 1, so you can use it in deploy scripts. Missing email is only a warning.

Running without a database

With no DATABASE_URL and no [database].url, gansey serve still starts and serves the welcome page, which says it is running without a database. This is useful for checking that the binary runs on a new machine. Pages, the theme, media, sign-in and the admin's screens all need the database.

Containers

The repository also has a container build for Linux. It compiles the admin and the binary, includes Postgres client tools for backups, and starts the site with gansey serve --migrate on port 8080. Configure the container with the same environment variables as any other install.

Other commands

Command	Does
gansey serve	start the site and the admin
gansey migrate	apply pending migrations and exit
gansey doctor	check the installation
gansey user create, reset-password, list	manage accounts without the admin
gansey backup now, list, restore <name>	database and media backups
gansey self-update	check for, install or roll back a core update
gansey site export, import	keep a whole site as files
gansey page export, import	pages as JSON
gansey theme export, import	theme kit packages
gansey mod ...	list, add, create, test and publish modules
gansey signing-key new, show	the site's signing key for modules
gansey render <file>	render a page document to HTML on stdout

gansey --help and gansey <command> --help list every flag.