Production installation runbook

Install Chronacta v1.0.0 on a clean Linux VM for production.

Prerequisites

Requirement	Version
OS	Linux amd64 (Ubuntu 22.04+ or equivalent)
Go (build from source)	1.25+ per `go.mod`
Open ports	gRPC 2113, metrics 9090; optional admin 8080, REST 8081, WS 8082
TLS certificates	Required in production profile
IdP	OIDC issuer URL (optional but recommended)

1. Clone release tag

git clone https://gitverse.ru/AndreyI/chronacta.git
cd chronacta
git checkout v1.0.0

Or download release artifacts from dist/ after make release VERSION=v1.0.0.

Verify checksums:

cd dist
sha256sum -c SHA256SUMS
# optional: gpg --verify SHA256SUMS.asc SHA256SUMS

2. Build and verify (from source)

make proto test-race vet build
./bin/chronacta-server --version

3. Layout

sudo useradd -r -s /bin/false chronacta
sudo mkdir -p /var/lib/chronacta/data /var/lib/chronacta/backups /etc/chronacta
sudo chown -R chronacta:chronacta /var/lib/chronacta

4. Production environment

Create /etc/chronacta/env:

# Core
CHRONACTA_PROFILE=production
CHRONACTA_DATA_DIR=/var/lib/chronacta/data
CHRONACTA_SCHEMA_DIR=/var/lib/chronacta/data/schemas
CHRONACTA_BACKUP_DIR=/var/lib/chronacta/backups

# Network
CHRONACTA_GRPC_PORT=2113
CHRONACTA_METRICS_ENABLED=true
CHRONACTA_METRICS_ADDRESS=127.0.0.1:9090

# Security (required in production)
CHRONACTA_AUTH_ENABLED=true
CHRONACTA_AUTH_STORE=/var/lib/chronacta/data/auth/users.json
CHRONACTA_TLS_ENABLED=true
CHRONACTA_TLS_CERT_FILE=/etc/chronacta/tls/server.crt
CHRONACTA_TLS_KEY_FILE=/etc/chronacta/tls/server.key

# HA (if cluster)
CHRONACTA_CLUSTER_REPLICATION_TOKEN=<generate-long-random-token>

# Gateways (optional)
CHRONACTA_REST_ENABLED=true
CHRONACTA_REST_ADDRESS=127.0.0.1:8081
CHRONACTA_WS_ENABLED=true
CHRONACTA_WS_ADDRESS=127.0.0.1:8082
CHRONACTA_WS_ALLOWED_ORIGINS=https://app.example.com

# OIDC (optional)
CHRONACTA_OIDC_ENABLED=true
CHRONACTA_OIDC_ISSUER_URL=https://idp.example.com/
CHRONACTA_OIDC_CLIENT_ID=chronacta

# Observability
CHRONACTA_OTEL_ENABLED=true
CHRONACTA_OTEL_ENDPOINT=otel-collector:4317

Generate TLS (example with internal CA) or use cert-manager / reverse proxy termination.

5. Bootstrap admin

sudo -u chronacta env $(cat /etc/chronacta/env | xargs) \
  ./bin/chronacta auth bootstrap -username admin -password '<initial-secret>'

Rotate password after first login. Prefer OIDC for day-to-day access.

6. systemd unit

/etc/systemd/system/chronacta.service:

[Unit]
Description=Chronacta server
After=network.target

[Service]
Type=simple
User=chronacta
EnvironmentFile=/etc/chronacta/env
WorkingDirectory=/opt/chronacta
ExecStart=/opt/chronacta/bin/chronacta-server
Restart=on-failure
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now chronacta

7. Smoke test

./bin/chronacta health
./bin/chronacta verify
curl -s http://127.0.0.1:9090/readyz
curl -s http://127.0.0.1:9090/metrics | head

Append/read test (with TLS and auth flags as configured):

./bin/chronacta login -username admin -password '<secret>'
./bin/chronacta append -stream smoke -type Created -data '{"ok":true}' -expected-version -2
./bin/chronacta read -stream smoke -from 1

8. Monitoring

Scrape http://127.0.0.1:9090/metrics with Prometheus.
Import grafana/chronacta-overview.json.
Load prometheus/chronacta-alerts.yaml.

9. Backup before go-live

./bin/chronacta backup create -output /var/lib/chronacta/backups/pre-ga.tar.gz

Document RPO/RTO per backup.md and replication.md.

10. Upgrade path

Follow upgrade-guide.md and ha-rolling-upgrade.md for cluster nodes.

Verification

The installation is complete when steps 1–7 finish without manual code patches.