Quick start#

This is the fastest path from nothing to a running Hinata stack. If you have Docker, you are about three commands away from a live server, database, object storage and a mail catcher — then you point the app at it and complete a short setup wizard.

The three commands#

From the root of the hinata-server repository:

cp .env.example .env
./deploy/generate-secrets.sh   # creates the Mongo keyfile + prints secrets for .env
docker compose up -d

What each step does:

1. cp .env.example .env — creates your local configuration file from the shipped template. Every setting is an environment variable; .env is where you fill in the ones that matter for your deployment. The full list lives in the Configuration reference.
2. ./deploy/generate-secrets.sh — generates the MongoDB replica-set keyfile (required for internal cluster auth) and prints strong random secrets for you to paste into .env. Run it before the first up.
3. docker compose up -d — pulls the images from ghcr.io/hinata-platform and starts the stack in the background.

What comes up#

docker compose up -d brings the whole development-style stack online:

Give it a few seconds, then check the server is healthy:

curl -s http://localhost:3356/api/v1/actuator/health
# {"status":"UP"}

Set the JWT secret — this is a MUST#

Hinata signs its stateless access and refresh tokens with an HS512 secret. The template ships this empty, and in production the server will not accept an empty or weak value. Generate a real one (at least 64 characters):

openssl rand -base64 64 | tr -d '\n'

Paste the output into .env:

HINATA_JWT_SECRET=PASTE_YOUR_64_CHAR_SECRET_HERE

After changing .env, recreate the server so it picks up the new environment:

docker compose up -d

Point the app at your server#

The server is only half the stack — the app is how people use it. The app is multi-server: it never hardcodes a URL, so you tell it where your server is.

Set your public API base in .env so tokens are issued for the right host and e-mail deep links point home:

HINATA_BASE_URL=https://api.track.example.com

Then, in the app, open the Server Manager, add your server (it runs a live connection test), and switch to it. On the web build you can simply visit the web app served alongside the API. For a local test, http://localhost:3356 works from the same machine.

Complete the setup wizard#

On first run the server has no organization or admin yet. Open the app against your new server and complete the in-app setup wizard: name your organization and create the first ADMIN account. From that moment you can create projects, invite people and start working.

Prefer a hands-off boot (for CI or scripted installs)? Skip the wizard entirely:

HINATA_SETUP_AUTO_COMPLETE=true
HINATA_SETUP_ORGANIZATION_NAME=Example Org
HINATA_SETUP_ADMIN_EMAIL=admin@example.com
HINATA_SETUP_ADMIN_USERNAME=admin
HINATA_SETUP_ADMIN_PASSWORD=change-me-please
HINATA_SETUP_ADMIN_DISPLAY_NAME=Admin

For the mechanics and a screenshot-by-screenshot walkthrough, see Setup & first run.

You're running Hinata#

That's a live stack: server, database, storage, mail, and an admin account. From here, the sensible next steps are all about making it production-grade.

Next steps#

• Production deployment — the real replica-set path with X.509 certificates and GHCR image tags.
• Configuration reference — every environment variable, what it does and its default.
• Reverse proxy & TLS — put a proxy in front, terminate TLS, and forward to ports 3356/3456.
• Requirements — host sizing, network and the pieces you'll want for a real deployment.