Deploy on Railway

The Railway template deploys the Studio path for Alquimia Stack into a clean Railway project. It creates Studio, Runtime, and the infrastructure services required for agent creation, model configuration, inference, registry storage, secrets, and persistence. The template also configures private networking, public domains, volumes, start commands, health checks, hidden Docker image credentials, generated internal secrets, and non-secret variables. Use the public Railway template as the recommended deployment path: Deploy Alquimia Stack on Railway

What the template deploys

Studio receives a public Railway domain. Runtime and infrastructure services communicate through Railway private networking unless a public Runtime domain is enabled by the template for integrations.

Required input

The default Railway UI deploy does not require user-provided variables before the first deploy. The template preconfigures Lite authentication and generates internal service credentials such as API_TOKEN, NEXTAUTH_SECRET, VAULT_TOKEN, database passwords, MinIO credentials, and Vault runtime credentials. Alquimia-owned Docker image credentials are hidden in the template, so deployers do not need DockerHub credentials. Model provider keys are added from Studio after deployment. Studio sends the secret value to Runtime, and Runtime stores it in Vault for inference-time resolution. The template includes a default Lite user:

Field	Value
Email	`admin@alquimia.ai`
Password	`alquimia`

Replace the default Lite user before using the deployment for shared environments, customer demos, or any environment with real data. To override the default user, set AUTH_LITE_USERS on studio. Generate a password hash from the Studio repo:

yarn hash-password <password>

Use the generated base64 bcrypt hash in this JSON shape:

[{"email":"admin@example.com","name":"Admin","password_hash":"<base64-bcrypt-hash>"}]

Deploy from Railway

Open Deploy Alquimia Stack.
Click Deploy Now.
Choose a Railway workspace and create a new project.
Deploy the template.
Wait until runtime, studio, runtime-postgres, redis, qdrant, minio, minio-init, vault, kafka, and oras-registry are healthy.
Open the generated Studio domain.
Sign in with admin@alquimia.ai and password alquimia.
In Studio, add a model connection and paste the provider API key.
Create or open an agent and run a test inference.

Maintainer: create or update the template

Railway does not deploy directly from repository files. The actual Railway template is generated from a clean Railway seed project that maintainers configure and validate before publishing. Use a clean seed project that matches the Studio-only template exactly:

Service names match the Studio-only template, including vault.
Internal URLs use Railway variable references such as ${{runtime.RAILWAY_PRIVATE_DOMAIN}}.
Studio has a public domain.
Stateful services have volumes.
Private alquimiaai/* images have hidden maintainer registry credentials.
Runtime uses ALQUIMIA_REGISTRY_SECRET_RESOLVER=vault.
The default Lite user is preconfigured as admin@alquimia.ai with password alquimia.

Generate an unpublished template from the seed project:

railway templates create \
  --project <seed-project-id> \
  --environment production \
  --json

Railway returns a template id. Publish or update the template with the public README:

railway templates publish <template-id> \
  --category AI/ML \
  --description "Deploy Alquimia Stack on Railway" \
  --readme-file /path/to/alquimia-railway/template/template-readme.md \
  --json

For a staging-only draft, you can generate from a staging environment:

railway templates create \
  --project <seed-project-id> \
  --environment staging \
  --json

Do not publish a template generated from an ad-hoc test environment unless service names, variables, volumes, registry credentials, and Railway variable references match the official Studio-only template.

Smoke checks

Set the generated public URLs locally:

export STUDIO_URL=https://<studio-domain>

Run:

curl -fsS "$STUDIO_URL" >/dev/null

From the Railway shell for each private service:

curl -fsS http://localhost:8080/health/readiness

Studio validation

In Studio, add a model connection and confirm the connection uses a Vault-backed secret name.
Create or open an agent configured with that model connection.
Send a short test inference and confirm Runtime responds.
If using the knowledge base flow, upload a small document from Studio and confirm the agent can use it.
Restart runtime, studio, runtime-postgres, qdrant, minio, vault, and oras-registry.
Confirm agents, model connections, uploaded artifacts, registry artifacts, and indexes remain available.

Cost estimate

Railway bills a plan minimum plus consumed resources. As of June 23, 2026, Railway lists these resource prices in its pricing docs:

Resource	Price
RAM	`$10 / GB / month`
CPU	`$20 / vCPU / month`
Network egress	`$0.05 / GB`
Volume storage	`$0.15 / GB / month`

For an idle-to-light Studio-only deployment, use this planning baseline:

Service group	Services	Estimated monthly Railway usage
Studio app	`studio`	`$1-3`
Runtime API and registry	`runtime`	`$3-5`
Runtime database	`runtime-postgres`	`$1-2`
Cache	`redis`	`<$1`
Vector store	`qdrant`	`$1-2`
Object storage	`minio`, `minio-init`	`$1-2`
Secret store	`vault`	`$1-2`
Event bus	`kafka` / Redpanda	`$5-7`
OCI registry	`oras-registry`	`<$1`
Estimated total	Studio-only template	`$15-25 / month`

This estimate excludes the Railway plan minimum, network egress, and external LLM provider usage. Kafka/Redpanda is usually the largest idle component because the template reserves a 512 MB broker target. Recalculate from the Railway project’s Usage tab after running representative workloads.

Troubleshooting

Symptom	Check
Private image pull fails	The template maintainer must configure hidden registry credentials for every private `alquimiaai/*` image. Deployer DockerHub credentials should not be required.
Runtime health check fails	Confirm `API_TOKEN`, Postgres variables, Redis URL, Vault variables, and `ALQUIMIA_REGISTRY_SECRET_RESOLVER=vault` are present on `runtime`.
Inference hangs or fails resolving secrets	Confirm `vault` is healthy, Runtime points to `http://vault.railway.internal:8200`, and the model connection was saved from Studio with a secret value.
Studio redirects incorrectly	Confirm `NEXTAUTH_URL` and `NEXT_PUBLIC_APP_URL` resolve to the Studio Railway public domain.
Private DNS fails	Confirm services are in the same Railway project environment and use `<service>.railway.internal` names.
Uploaded artifacts disappear after restart	Confirm volumes are attached to `runtime`, `qdrant`, `minio`, and `oras-registry`.

Overview

Getting started

Products

What the template deploys

Required input

Deploy from Railway

Maintainer: create or update the template

Smoke checks

Studio validation

Cost estimate

Troubleshooting

​What the template deploys

​Required input

​Default login

​Deploy from Railway

​Maintainer: create or update the template

​Smoke checks

​Studio validation

​Cost estimate

​Troubleshooting

What the template deploys

Required input

Default login

Deploy from Railway

Maintainer: create or update the template

Smoke checks

Studio validation

Cost estimate

Troubleshooting