Configuration
Every command, flag and environment variable the base binary reads, taken
from the code. A Go program that embeds Base gets the root flags from
base.New, the serve flags, the core variables, and the variables of the
plugins it registers.
Commands
| Command |
What it does |
base serve [domain...] |
Runs the server. Naming domains turns on HTTPS with certificates from Let's Encrypt. |
base migrate up|down [n]|create <name>|collections|history-sync |
Applies, reverts or writes migrations. See hooks. |
base update |
Replaces the binary with the latest GitHub release. No current release carries binaries, so it stops with missing asset. |
base cli <command> |
An HTTP client for a running Base: collection, record, whoami, login, crons, daemon, status, rpc, config, self, cluster, operator. |
Root flags
These apply to every command.
| Flag |
Default |
Meaning |
--dir |
$DATA_DIR, else base_/data beside the path the binary was started by |
Data directory. ./base uses ./base_/data; a base found on PATH uses base_/data in the working directory. |
--dev |
false, or true under go run |
Log SQL statements and debug output. |
--encryptionEnv |
none |
Name of an environment variable whose 32-character value encrypts stored settings. |
--queryTimeout |
30 |
Seconds before a SELECT is cancelled. |
--zap |
$ZAP_ADDR, else the HTTP host on $ZAP_PORT |
ZAP listen address. See listeners. |
--mdns |
$ZAP_MDNS, else off |
Advertise ZAP over mDNS and connect to the peers found. Never while ZAP listens on loopback. |
--no-mdns |
off |
Keep mDNS off even when --mdns or ZAP_MDNS asks for it. |
--hooksDir |
hooks beside the data directory |
JavaScript hooks. |
--hooksWatch |
true |
Restart when a file under the hooks directory changes. Not on Windows. |
--hooksPool |
15 |
Interpreters kept for running hook handlers. |
--migrationsDir |
migrations beside the data directory |
JavaScript migrations. |
--automigrate |
true |
Write a migration when a superuser changes a collection over /v1. |
--publicDir |
public beside the binary |
Parsed, but serves nothing: Base registers its own GET /{path...} route (the admin UI, or a 404 when the admin is off) before the binary checks for one. |
--indexFallback |
true |
Parsed, but has no effect, for the same reason. |
-v, --version |
|
Print the version. |
serve flags
| Flag |
Default |
Meaning |
--http |
127.0.0.1:8090, or 0.0.0.0:80 when domains are named |
HTTP address. While HTTPS is on, it only redirects and answers ACME challenges. |
--https |
none, or 0.0.0.0:443 when domains are named |
HTTPS address. |
--origins |
* |
Allowed CORS origins. |
update flags
| Flag |
Default |
Meaning |
--backup |
true |
Back up the data directory after replacing the binary. |
cli flags
| Flag |
Default |
Meaning |
--url |
$BASE_URL, else http://127.0.0.1:8090 |
Base to call. |
--token |
$BASE_TOKEN, else the file ~/.config/base/token ($XDG_CONFIG_HOME/base/token when set) |
Token to send. Get it from IAM. |
--base |
none |
Org to act in, sent as X-Org-Id. |
--format |
table on a terminal, else json |
table, json or yaml. |
--mainnet (-m), --testnet (-t), --devnet (-d), --dev |
$APP_ENV, then $BASE_ENV, else local |
Environment for cluster, operator and status. |
Environment
A boolean accepts what Go's strconv.ParseBool accepts: 1, t, true,
TRUE and their false counterparts. The exceptions are S3_ENABLED (true in
any case), CLOUD_SQL_ENABLED (exactly true) and WAITLIST_OPEN (1, true
or yes in any case).
Core
| Variable |
Default |
Meaning |
DATA_DIR |
|
Data directory when --dir is not given. |
BASE_API_PREFIX |
/v1 |
Where the API is mounted. /v1/iam and /healthz stay where they are. |
BASE_ENABLE_ADMIN_UI |
off |
Serve the admin UI at /. It signs in through IAM. |
BASE_FRAME_ANCESTORS |
'self' |
CSP frame-ancestors for the admin UI. |
IAM_DISPLAY_NAME |
empty |
Display name of the iam provider in auth-methods. |
NATS_URL |
none |
Publish record create, update and delete events to NATS. |
S3_ENABLED |
off |
Store files in S3 rather than the data directory. |
S3_ENDPOINT, S3_BUCKET_NAME (or S3_BUCKET), S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_FORCE_PATH_STYLE |
|
The S3 connection, read when S3_ENABLED is set. |
THUMBS_MAX_WORKERS |
CPUs + 2 |
Thumbnails generated at once. |
THUMBS_MAX_WAIT |
60 |
Seconds a thumbnail request waits for a worker. |
FILES_DELETE_MAX_WORKERS |
2000 |
File deletions run at once. |
BASE_PRIVATE_MAX_TAG_BYTES |
1048576 |
Largest value in /v1/private, the per-user encrypted blob store. |
BASE_PRIVATE_MAX_USER_BYTES |
104857600 |
Total /v1/private bytes per user. |
BASE_GOJAVM_POOL_SIZE |
8 |
Interpreters for /v1/functions, which is how many functions run at once. |
TASKS_EMBED |
off |
Run the Tasks engine inside Base. See listeners. |
TASKS_EMBED_ADDRESS |
<data dir>/tasks.sock |
Where the embedded engine listens. |
TASKS_NAMESPACE |
default |
Namespace of the embedded engine. |
TASKS_ZAP |
none |
A Tasks server to use over ZAP. |
TASKS_URL |
none |
A Tasks server to use over HTTP. With no Tasks server, scheduled jobs run on timers inside the process. |
ZAP
| Variable |
Default |
Meaning |
ZAP_ADDR |
none |
ZAP listen address. --zap wins over it. |
ZAP_PORT |
9999 |
Port used on the HTTP host when no address is given. |
ZAP_MDNS |
off |
The same as --mdns. |
ZAP_DISABLED |
off |
Do not start ZAP. |
IAM, orgs and KMS
The binary registers plugins/org when IAM_ENDPOINT or IAM_URL is set.
| Variable |
Default |
Meaning |
IAM_ENDPOINT (or IAM_URL) |
none |
IAM origin. Turns on IAM sign-in and a Base per org. |
IAM_ADDRESS |
none |
Where Base reaches the IAM service to check tokens and keys, when that is not IAM_ENDPOINT. A bare host:port is ZAP. |
IAM_CLIENT_ID, IAM_CLIENT_SECRET |
none |
The IAM application Base presents when it calls IAM itself, and to KMS over HTTPS. |
IAM_ORGANIZATION |
none |
The IAM org Base belongs to. Required with KMS_ENDPOINT: the master key is read beneath it. |
KMS_ENDPOINT (or KMS_URL) |
none |
Secrets store: host:port, zap://host:port, https://..., or zap+mdns://_kms._tcp to discover it. Base reads its master key from it when it starts. |
LUX_MNEMONIC (or MNEMONIC) |
none |
Seed of the identity Base signs KMS requests with. Required for KMS over ZAP. |
KMS_ENV |
prod |
Environment of the secrets Base reads. |
KMS_SERVICE_PATH |
hanzo/base |
Derivation path of that identity. |
KMS_NODE_ID |
hanzo-base |
Node name the KMS client presents. |
IDV_ENDPOINT |
none |
Upstream for /v1/idv/*. Unset, /v1/idv/status answers {"enabled":false} and the rest 503. |
The master key is base/MASTER_KEY_B64 beneath IAM_ORGANIZATION: 32 bytes,
base64-encoded. Each org Base is encrypted under a key derived from it, and an
org Base that is already a plaintext file is refused. With no key stored, org
Bases are not encrypted, and Base logs that when it starts. Base does not start
when KMS cannot be read, when the key is not 32 bytes, or when a key is stored
and SQLCipher is not linked. The image is built with CGO_ENABLED=0, which
links none.
Replication
| Variable |
Default |
Meaning |
BASE_NETWORK |
standalone |
quasar replicates writes to peers. |
BASE_PEERS |
none |
Peers as comma-separated host:port. Replication listens only when this names one. |
BASE_SHARD_KEY |
none |
Required with quasar: a field of the verified identity such as user_id or org_id, or header:<Name>. |
BASE_REPLICATION |
1 |
Members that hold each shard. |
BASE_NODE_ID |
$HOSTNAME |
This member's id. Required with quasar. |
BASE_NODE_ROLE |
validator |
validator or archive. |
BASE_ARCHIVE |
off |
s3://bucket/prefix to archive frames. |
BASE_LISTEN_P2P |
:9999 |
Peer listener, bound exactly as written. The port must be a number. |
BASE_LISTEN_HTTP |
:8090 |
Read, but opens nothing. |
BASE_PEER_HTTP_ENDPOINTS |
none |
Comma-separated peer=url pairs: where to send a write that a peer owns. |
BASE_PEER_HTTP_PORT |
8090 |
HTTP port assumed for a peer missing from that list. |
AWS_REGION, AWS_ENDPOINT_URL, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN |
|
Credentials for an s3:// archive. |
BASE_ENCRYPT, BASE_TLS_CA, BASE_TLS_SERVER_CERT, BASE_TLS_SERVER_KEY, BASE_TLS_ALLOWED_SANS |
|
Refused. Setting any of them stops startup with an explanation. |
Plugins in the binary
The waitlist plugin is always registered and serves /v1/waitlist/*.
| Variable |
Default |
Meaning |
TURNSTILE_SECRET_KEY |
none |
Cloudflare Turnstile secret for checking joins. |
WAITLIST_ADMIN_SECRET |
none |
Secret for boost and export. |
WAITLIST_AWARD_SECRET |
none |
Secret for award. |
WAITLIST_DEFAULT_SLUGS |
none |
Comma-separated waitlists to create at startup. |
WAITLIST_ACCESS_CAPACITY |
0 |
Grant access to the top N entries by rank. |
WAITLIST_OPEN |
off |
Give everyone access. |
POINTS_REFERRAL, POINTS_SHARE, POINTS_INVITE_SENT, POINTS_INVITE_CONVERTED, POINTS_SOCIAL, POINTS_HANZOD, POINTS_SIGNUP |
10, 2, 1, 5, 15, 25, 0 |
Points per event. |
The other three are off unless enabled.
| Variable |
Default |
Meaning |
BOOTNODE_ENABLED |
off |
Serve the bootnode developer platform. |
BOOTNODE_API_KEY_SALT |
none |
Salt for issued API keys. Required when IAM_URL is not a local host. |
BOOTNODE_ALLOWED_ORGS |
hanzo, zoo, lux, pars |
IAM orgs allowed to sign in. |
BOOTNODE_K8S_NAMESPACE |
bootnode |
Namespace for the resources it applies. |
IAM_URL, IAM_CLIENT_ID, IAM_CLIENT_SECRET |
|
The IAM application for its OAuth2 code exchange. |
FRONTEND_URL |
http://localhost:3001 |
Redirect base when a request names none. |
COMMERCE_URL, COMMERCE_API_KEY |
none |
Billing client. An empty key turns billing off. |
KUBE_APISERVER, KUBE_TOKEN, KUBE_INSECURE_SKIP_TLS_VERIFY |
|
Kubernetes API, when not running in a cluster. |
KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT |
|
Kubernetes API from inside a cluster. |
CALENDAR_ENABLED |
off |
Serve the booking API at /v1/calendar. |
CALENDAR_SEED_HANDLE |
none |
Create a bookable host with this handle at startup. |
CALENDAR_SEED_OWNER, CALENDAR_SEED_TZ, CALENDAR_SEED_TITLE, CALENDAR_SEED_LOCATION |
the handle, America/Los_Angeles, Intro, https://meet.hanzo.ai/<handle> |
That host's details. |
CLOUD_SQL_ENABLED |
off |
Serve /v1/cloud-sql and /v1/meta. |
CLOUD_SQL_META_URL, CLOUD_SQL_COMPUTE_HOST, CLOUD_SQL_PG_USER, CLOUD_SQL_PG_PASS |
none |
The managed PostgreSQL service it drives. |
Plugins you link yourself
The binary does not include these. A program that registers one reads its
variables.
| Plugin |
Variables |
plugins/ha |
BASE_LOCAL_TARGET, BASE_PEERS, BASE_STATIC_WRITER, BASE_NODE_ID |
plugins/replicate |
REPLICATE_S3_ENDPOINT, REPLICATE_S3_PATH |
plugins/tasks |
TASKS_ENABLED (or HANZO_TASKS_ENABLED), TASKS_ADDRESS (or HANZO_TASKS_ADDRESS), TASKS_NAMESPACE (or HANZO_TASKS_NAMESPACE), TASKS_QUEUE, TASKS_WORKER |
plugins/pyvm, plugins/v8vm, plugins/wasmvm, plugins/starkvm |
BASE_PYVM_POOL_SIZE, BASE_V8VM_POOL_SIZE, BASE_WASMVM_POOL_SIZE, BASE_STARKVM_POOL_SIZE |
Read by a dependency
| Variable |
Meaning |
HANZO_SQLITE_RAMFS_DIR |
Where the pure-Go encrypted SQLite codec keeps its temporary plaintext copy, when this directory is RAM-backed (on macOS, a tmpfs mount). Otherwise the codec uses /dev/shm, and failing that the OS temp directory. The copy is deleted on close. |
HOSTNAME |
Default replication node id. |
The cli command
| Variable |
Meaning |
BASE_URL, BASE_TOKEN |
Defaults for --url and --token. |
XDG_CONFIG_HOME |
Where the token file and base/config.json live. |
APP_ENV, BASE_ENV |
Default environment when no environment flag is given. |
zeekayandHanzo Dev
31eb0797ee