From a bare machine to your own system talking to it

Running it locally

The gateway keeps its own metadata in PostgreSQL 16 — the same store in development and in production. Since ADR 0018 collapsed it to one, you need a local PostgreSQL before anything else. What that buys is a single source of truth for the schema.

The lines below are everything it takes to get from a bare machine to an open console. You create the database; the server does the rest on startup — migrations, reference data, demo seed.

# create the database — add vela_test too if you run the backend suite
createdb vela_gateway

# backend on :8080 — it applies migrations itself at startup
cd backend && go run ./cmd/server

# frontend on :5173 — Vite proxies /api to :8080
cd frontend && npm install && npm run dev

• The default DSN points at vela_gateway on 127.0.0.1:5432 and deliberately omits user=, so libpq falls back to the current OS user — which is exactly the shape a Homebrew PostgreSQL comes in.
• If you would rather not install PostgreSQL, the docker compose file at the repository root starts one bound to 127.0.0.1 only; going that way you must pass VELA_PG_DSN explicitly.
• The first boot of an empty database creates one platform administrator and no instances — add those from the Config page. A dev build pre-fills that account on the sign-in page; a production build does not. Instances with no credentials run in simulation under the dev profile; in production they always answer that the instance has no real execution credentials.

Production deployment and the upgrade order

What you deploy is one binary: the API, the compiled frontend SPA and the SQL migrations are all inside it. Three subcommands — version prints the build string, migrate only creates and upgrades tables, init runs the migrations plus reference data and then creates the administrator.

The migrations are embedded, and the server applies them itself at startup, exiting if they fail. That makes the separate migrate step optional now — but it is worth keeping: it puts the outcome and the duration of the migration somewhere you can see them.

# version string: unset VERSION falls back to git describe — this is what the version subcommand prints
VERSION="${VERSION:-$(git describe --tags --always --dirty)}"
rm -rf dist && mkdir -p dist/web

# the frontend build goes to the backend web_dir
(cd frontend && npm ci && npm run build) && cp -r frontend/dist/* dist/web/

# cross-compile the backend — pure Go, no C toolchain
(cd backend && GOOS=linux GOARCH=amd64 go build -trimpath \
  -ldflags "-s -w -X main.version=$VERSION" -o ../dist/vela-gateway ./cmd/server)

• Production DSNs must spell out sslmode: the default mode quietly falls back to plaintext when the server does not offer TLS, and the credentials plus every audit record travel over that connection.
• On PostgreSQL 15 and later, after creating the database you have to connect to that database and grant schema privileges there — running it while connected elsewhere only changes the wrong object. This is the most common stumble on a fresh install.

The startup self-check: can anyone still approve these?

This check exists because of a real deadlock: the approving role had exactly one member, and every ticket was raised by that person. Every layer of validation passed, and then two-person control meant not one of them could be approved.

So every boot starts by answering one question: can anyone still approve these paths? Each of the three findings below logs a WARN, and each one carries a fix.

What does refuse to start is a different list

The staffing check never blocks. Each of these exits immediately:

• An empty database DSN in production — and all three entry points refuse it, serve, migrate and init alike. libpq reads an empty DSN as "local socket, OS user, database named after that user" and genuinely connects, so forgetting it quietly points the gateway at an unrelated database.
• A JWT signing key in production that is too weak, too short, or built from too few character classes.
• An invalid reverse-proxy trust list — refused in every environment. The web framework silently falls back to trusting every proxy when that value does not parse, which would let a client forge its source address past the IP allowlists.
• A failed migration, or --no-migrate on a schema that is behind.
• A failed seed.

A handful of things only log a WARN: TLS not enabled in production, no static encryption key set, webhooks allowed to reach private networks in production, an unrecognised environment name, and a web_dir with no index.html or assets directory.

Integrating over the open API

One credential, one set of endpoints, idempotency backed by a unique index. Credentials are issued from system settings, always against an explicitly chosen service account. Issuing returns a token shaped key.secret, and only a bcrypt hash of the secret is stored, so the plaintext exists once.

Send the token as Authorization: Bearer, or split it across the X-Vela-Key and X-Vela-Secret headers. What gets injected afterwards is that service account — which is why the capability matrix, the label scope and audit attribution downstream all keep working untouched.

Endpoints

Standards review as a CI merge gate

The dialect is decided by the target instance: the same SQL trips different rules against an Oracle instance and a TiDB instance, so you give either the instance or the connection id.

# no ticket is created — this only returns the review
curl -X POST https://<gateway>/api/v1/open/sql-review \
  -H "Authorization: Bearer $VELA_TOKEN" \
  -F "instance=order-cluster" \
  -F "file=@migrations/V12__archive.sql"

The passed flag means "no error-level findings", not "no findings at all": a release that every warning could stop is a release nobody could ever ship. Each finding carries the rule code, its level, which statement it was and the line it starts on.

Submitting a ticket

A title, the target instance and database, the change type, the SQL or a script, and your own reference number. Scripts travel three ways: file as multipart, script inline in the JSON, or base64; the ceiling is 15MB, measured from the bytes actually read.

# submit one SQL upgrade ticket
curl -X POST https://<gateway>/api/v1/open/releases \
  -H "Authorization: Bearer $VELA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

# body.json
{
  "title":       "Add a memo column to the order table",
  "externalRef": "CHG-2026-0001",
  "instance":    "order-cluster",
  "database":    "orders",
  "changeType":  "ddl",
  "sql":         "ALTER TABLE tbl_order ADD COLUMN memo VARCHAR(64) NOT NULL DEFAULT ''",
  "reason":      "Ticket #123"
}

Conventions worth knowing first

• Every response is HTTP 200; success is the code field in the body being 0. The callback endpoint and the WebSocket handshake are the only exceptions.
• Error codes: 40100 invalid credential, do not retry; 40300 not permitted; 40301 source IP outside this credential’s allowlist; 42800 second factor required; 40001 bad parameters; 50000 server error, safe to retry with backoff.
• You cannot pick a release pipeline in the request: sending one rejects the whole ticket rather than ignoring it, because silently ignoring it would let the caller believe the choice took effect.
• Polling every 10 to 30 seconds is plenty; after an approval the gateway takes at most 15 seconds to push the pipeline forward.
• A ticket that is already executing refuses to be aborted — a false "aborted" is more dangerous than having no such button.
• An instance name that matches more than one instance is an error rather than a guess: guessing wrong means the change landed on a different database.

The contract, online

GET /openapi.yaml returns the contract and GET /docs opens Swagger UI — vendored into the binary rather than loaded from a CDN, so it opens on a machine with no internet access. The contract covers 143 operations across 113 paths.

External Lark approval

This moves approval of high-risk commands out of the console: the external approval service pushes an interactive Lark card, a human decides on the card, and a callback marks the ticket approved or rejected. In-console approval stays as the fallback, and both paths converge on the same atomic decision core.

The callback does not execute anything. After approval someone with the right to do so still returns to the approvals page and presses execute — what the approver pressed was "I agree", not "run it now" (ADR 0010).

What you configure — all of it runtime settings, not deployment-time environment variables

Settings › Approval › External Lark approval in the console. The values live in the database and take effect without a restart.

There is a separate Lark integration under Settings › Notifications that is easy to confuse with this one: it only pushes a card, receives no callbacks and changes no outcome.

When it will not connect

Read the originals in the repository

This page is the commands and the parameters; the long form lives in the repository.

• README.mdFeature overview, tech stack, quick start.
• DEPLOY.mdCreating and granting the database, why sslmode has to be spelled out, the upgrade section, and the startup log lines worth watching once you are live.
• docs/adr/Architecture decision records — why each decision was made, and which alternative was rejected.
• docs/开放接口对接文档.mdOpen API fields, error codes and integration conventions.
• docs/external-approval-setup.mdConfiguring external Lark approval, how to roll it out, and how to debug it.
• backend/docs/openapi.yamlThe source of the online contract — it sits under the backend, not in the repository-root docs directory.