Repository navigation
Getting Started
Two paths. Try it runs the server and puts one file in and out. Use it on
a project needs no server at all: template init writes a starter into a
folder.
- Docker with Compose β the only requirement for the stack.
- Go (the version in
go.mod) β only if you build the CLI or run from source. - Or neither: a release archive carries a prebuilt CLI and server.
Two local files come first β the configuration and the database secret. Both are
gitignored, and make setup creates them from the committed examples:
make setup
make up # or: docker compose upmake up builds the two images (web/Dockerfile for nginx, Dockerfile.api for
the API), waits for PostgreSQL to be healthy, runs the migrate service once,
then starts the API on :4000 and the UI on :5173.
| Role | Where | Port |
|---|---|---|
| Web UI (nginx) |
web service |
5173 |
| API |
api service |
4000 |
| API reference (Swagger UI) |
/docs on either |
β |
| PostgreSQL |
db service |
5432 |
Without make, copy .env.example to .env and
secrets/db_password.txt.example to secrets/db_password.txt, then
chmod 600 .env secrets/db_password.txt, and run docker compose up.
Uploaded bytes live on the api-data volume, so they survive
docker compose down (down -v removes them too).
The CLI is a separate binary. Build it with make build_cli (Go only) or use a
release archive β see Releases.
./build/cli/linux/eznit signup # Enter Email / Password / Confirm
./build/cli/linux/eznit login # stores a session token in ~/.eznit/config.json (0600)
./build/cli/linux/eznit upload # file path: ./notes.txt
./build/cli/linux/eznit list # the files you own
./build/cli/linux/eznit download # id file: <id> / destination folder path: ./outThe core commands prompt for what they need. signup and login are the only
unauthenticated identity commands; everything else that touches your own rows
needs the session.
This path needs no server, no login and no Docker. It writes files into a folder you name:
eznit template init --kind opencode --target ./demo--kind accepts opencode, codex, copilot, cursor, windsurf or
generic; the starter asks for the project name, description and language and
fills them in. What each kind writes is on
Templates and skills.
To share that folder and pull it elsewhere, publish it to a running instance:
eznit template publish ./demo --public # prompts name, kind, description, defaults
eznit template list # note the id
eznit template apply <id> --target ../another-projectapply asks the variables on the machine that writes the files β a value you
type never travels to the server.
To carry the template to a machine with no server at all, export it to one file:
eznit template export <id> -o setup.eznit
eznit template apply --from-file setup.eznit --target ../another-projectA release archive is not a source checkout: there is no go.mod, no web/,
and no image to build. Start the database and migrations from the published
images, then run the prebuilt server:
cp secrets/db_password.txt.example secrets/db_password.txt # then edit it
cp .env.example .env # then edit it
docker compose up db migrate
DB_HOST=localhost DB_PORT=5432 ./eznit-server # serves the embedded UI on :4000Set the database password for the host-run server too: DB_PWD, or
DB_PASSWORD_FILE pointing at secrets/db_password.txt. RUNNING.md in the
bundle says the same, and what it does not prove. Plain docker compose up is
the source-checkout path β in a bundle it would try to build an image the
archive does not contain.
The bundle also carries eznit-gui. Run it from inside the extracted folder β
the Server tab looks for eznit-server beside the window. The first run is:
- start a database in that folder:
docker compose up -d db migrate; - Server β Configuration β Create .env, set the database password, Save;
- Server β Start: the Output tab shows the log and the status dot turns green;
- Files: This machine, then Test, then Connect, and create the first account β it is the instance's admin.
The window is also a client of a server somewhere else, and that needs no bundle: type the address into the Files header, Test it, Connect. The Server tab is not involved.
RUNNING.md in the bundle says the same, and what it does not prove.
- Templates and skills β what to put in a template and how to share it
- CLI Reference β the full command surface
- Configuration β every variable, secret and port
- Troubleshooting β if a port is busy or a secret is missing