feat: updated installation

Author: nicosammito

content/general/install.mdx

@@ -60,36 +60,79 @@ HOSTNAME=localhost
 HTTP_PORT=80
 HTTPS_PORT=443
 SSL_ENABLED=false
-SSL_CERT_FILE= # must be located in ./certs, defaults to "<hostname>.pem"
-SSL_KEY_FILE= # must be located in ./certs, defaults to "<hostname>.key"
+# must be located in ./certs, defaults to "<hostname>.pem"
+SSL_CERT_FILE=
+# must be located in ./certs, defaults to "<hostname>.key"
+SSL_KEY_FILE=
 
 INITIAL_ROOT_PASSWORD=root
 INITIAL_ROOT_MAIL=root@code0.tech
-INITIAL_RUNTIME_TOKEN= # can be used to create a global runtime with given token
+# can be used to create a global runtime with given token
+INITIAL_RUNTIME_TOKEN=runtime
 
 # Runtime config
 AQUILA_SAGITTARIUS_URL=http://nginx:80
-AQUILA_SAGITTARIUS_TOKEN=
+AQUILA_SAGITTARIUS_TOKEN=runtime
 DRACO_REST_PORT=8084
+DRACO_REST_HOST=127.0.0.1
 
 TAURUS_AQUILA_TOKEN=taurus
 DRACO_REST_AQUILA_TOKEN=draco-rest
 DRACO_CRON_AQUILA_TOKEN=draco-cron
 
+AQUILA_GRPC_CONNECT_TIMEOUT_SECS=2
+AQUILA_GRPC_REQUEST_TIMEOUT_SECS=10
+SAGITTARIUS_UNARY_RPC_TIMEOUT_SECS=10
+
 # Active services
-COMPOSE_PROFILES=ide,runtime
+# Available services: ide, runtime, ide_velorum (AI orchestrator)
+COMPOSE_PROFILES=ide,runtime,ide_velorum
 
 # Image config
 IMAGE_REGISTRY=registry.gitlab.com/code0-tech/packages
 IMAGE_TAG=
-IMAGE_EDITION= # ce or ee
+# ce or ee
+IMAGE_EDITION=
+
+# Sagittarius config
+# change these to new secret values
+SAGITTARIUS_DB_ENCRYPTION_PRIMARY_KEY=YzaMv4bXYK84unYIQI4Ms4sV3ucbvWs0
+SAGITTARIUS_DB_ENCRYPTION_DETERMINISTIC_KEY=jgTaxTqzM15ved1S8HdXrqrjfCfF5R0h
+SAGITTARIUS_DB_ENCRYPTION_KEY_DERIVATION_SALT=Z6zcLTgobXLYjXUslRsLMKxvXKq3j6DJ
+SAGITTARIUS_RAILS_SECRET_KEY_BASE=MVMD6CtQwEWrQ28TdokQakbG2FG5abOn
+
+# Velorum config
+# VELORUM_ENABLED=false (override, default checks if COMPOSE_PROFILES contains ide_velorum)
+VELORUM_HOST=velorum
+VELORUM_PORT=50051
+# change to a random value
+VELORUM_JWT_SECRET=088cfc7a7fc2b07696d8ee5e1ea9d642
+
+# example, GPT5 in the variable name can be changed to other values. This set of variables can be repeated multiple times
+# VELORUM_MODEL_GPT5_IDENTIFIER=gpt-5
+# VELORUM_MODEL_GPT5_NAME='GPT 5'
+# VELORUM_MODEL_GPT5_CAPABILITIES=explain,generate
+# if using a non-default base-url
+# VELORUM_MODEL_GPT5_API=
+# or openrouter/openai/gpt-5, etc depending on the provider
+# VELORUM_MODEL_GPT5_PROVIDER=openai/gpt-5
+# authentication token
+# VELORUM_MODEL_GPT5_AUTH=your-secret-token
+# token cost multiplier for this model
+# VELORUM_MODEL_GPT5_TOKEN_COST=1
 
 # Internal config options
 SAGITTARIUS_RAILS_HOST=sagittarius-rails-web
 SAGITTARIUS_RAILS_PORT=3000
+SAGITTARIUS_CABLE_HOST=sagittarius-rails-cable
+SAGITTARIUS_CABLE_PORT=3000
 SAGITTARIUS_GRPC_HOST=sagittarius-grpc
 SAGITTARIUS_GRPC_PORT=50051
 SAGITTARIUS_LOG_LEVEL=info
+# web threads and grpc threads must be lower than db pool size
+SAGITTARIUS_RAILS_WEB_THREADS=3
+SAGITTARIUS_RAILS_GRPC_THREADS=6
+SAGITTARIUS_DB_POOL_SIZE=8
 SCULPTOR_HOST=sculptor
 SCULPTOR_PORT=3000
 POSTGRES_HOST=postgres
@@ -106,6 +149,20 @@ POSTGRES_PASSWORD=sagittarius
 - `INITIAL_ROOT_PASSWORD`: The secure password for your first login.
 - `IMAGE_EDITION`: Set this to ce for the Community Edition or ee for the Enterprise Edition. This
   determines which Docker images will be pulled.
+- `COMPOSE_PROFILES`: Controls which services are started. Available profiles are `ide`, `runtime` and
+  `ide_velorum` (AI orchestrator). Remove `ide_velorum` if you don't want to run the AI orchestrator.
+
+### Secrets
+
+The following values must be replaced with newly generated secrets before going to production. The defaults
+in the template are only meant to make local testing easier:
+
+- `SAGITTARIUS_DB_ENCRYPTION_PRIMARY_KEY`, `SAGITTARIUS_DB_ENCRYPTION_DETERMINISTIC_KEY`,
+  `SAGITTARIUS_DB_ENCRYPTION_KEY_DERIVATION_SALT`: Keys used to encrypt sensitive data in the Sagittarius
+  database.
+- `SAGITTARIUS_RAILS_SECRET_KEY_BASE`: Base secret used by Rails to sign and encrypt session data.
+- `VELORUM_JWT_SECRET`: Secret used by Velorum to sign JWTs. Only required when the `ide_velorum` profile is
+  active.
 
 ### Setup initial runtime
 
@@ -181,4 +238,82 @@ docker compose up -d
 
 </Steps>
 
+## Setup Velorum (AI orchestrator)
+
+Velorum is the AI orchestrator that powers CodeZero's AI features. It exposes a unified interface to one or
+more language models, which are configured purely through environment variables.
+
+<Steps>
+<Step>
+
+## Enable the Velorum profile
+
+Make sure the `ide_velorum` profile is part of `COMPOSE_PROFILES` in your `.env` file:
+
+```bash
+COMPOSE_PROFILES=ide,runtime,ide_velorum
+```
+
+You can opt out of the AI orchestrator at any time by removing `ide_velorum` from the list and restarting
+the containers. To force-disable Velorum even when the profile is active, set `VELORUM_ENABLED=false`.
+
+</Step>
+<Step>
+
+## Configure the Velorum service
+
+The following variables configure the Velorum service itself:
+
+- `VELORUM_HOST`: The hostname Sagittarius uses to reach Velorum. Defaults to the in-network `velorum`
+  service.
+- `VELORUM_PORT`: The gRPC port Velorum listens on (default `50051`).
+- `VELORUM_JWT_SECRET`: Secret used to sign JWTs issued by Velorum. Replace the value from the template
+  with a freshly generated random string.
+
+</Step>
+<Step>
+
+## Configure AI models
+
+Each model Velorum should expose is configured through a set of `VELORUM_MODEL_<SLOT>_*` variables. The
+`<SLOT>` part of the variable name is a free-form identifier you choose (e.g. `GPT5`, `CLAUDE`, `LLAMA`)
+and is used only to group the variables for one model together. Repeat the set of variables for every
+model you want to register.
+
+```bash
+VELORUM_MODEL_GPT5_IDENTIFIER=gpt-5
+VELORUM_MODEL_GPT5_NAME='GPT 5'
+VELORUM_MODEL_GPT5_CAPABILITIES=explain,generate
+# if using a non-default base-url
+VELORUM_MODEL_GPT5_API=
+# or openrouter/openai/gpt-5, etc depending on the provider
+VELORUM_MODEL_GPT5_PROVIDER=openai/gpt-5
+VELORUM_MODEL_GPT5_AUTH=your-secret-token
+VELORUM_MODEL_GPT5_TOKEN_COST=1
+```
+
+- `IDENTIFIER`: Stable identifier used by the rest of CodeZero to reference this model.
+- `NAME`: Human-readable name shown in the dashboard.
+- `CAPABILITIES`: Comma-separated list of capabilities this model supports (e.g. `explain`, `generate`).
+- `API`: Optional. Override when the provider is reached through a non-default base URL.
+- `PROVIDER`: Provider/model string in the format expected by Velorum, e.g. `openai/gpt-5` or
+  `openrouter/openai/gpt-5`.
+- `AUTH`: Authentication token used to call the provider.
+- `TOKEN_COST`: Token cost multiplier applied to usage of this model.
+
+</Step>
+<Step>
+
+## Finalize the setup
+
+After updating the `.env` file, restart the containers so Velorum and Sagittarius pick up the new
+configuration:
+
+```bash
+docker compose up -d
+```
+
+</Step>
+</Steps>
+
 Your CodeZero instance is now fully configured and ready to manage your enterprise flows and organizational structures.