shaide server

This repository contains the shaide server.

Environment variables

The following table describes the current environment variables that we use.

Env var name	Optional?	Comment
ADMIN_PASSWORD	No	Password used to create the initial admin user
JWT_SECRET	No	Secret used to sign user JWTs; must be at least 32 bytes
SHAIDE_SERVER_UI_FQDN	No	The server UI address
SHAIDE_SERVER_UI_PORT	No	The server UI port
WEBAPP_URL	Yes	WebApp upstream URL for the /app reverse proxy (unset: no proxy)
GCP_API_KEY	Yes	GCP API key/token (if empty, auth must be provided by other means)
HOST	Yes	Server bind host (default: 0.0.0.0)
PORT	Yes	Server bind port (default: 8080)
VECTOR_DB_URL	Yes	Vector DB URL (default: http://localhost:6334)
DATABASE_URL	Yes	Database URL used by SQLx tooling/migrations

Example .env file.

ADMIN_PASSWORD=admin_password
JWT_SECRET=replace_with_a_random_secret_of_at_least_32_bytes
SHAIDE_SERVER_UI_FQDN=control-panel.localhost
SHAIDE_SERVER_UI_PORT=3000
WEBAPP_URL=http://localhost:3001
GCP_API_KEY=gcp_api_key
HOST=0.0.0.0
PORT=8080
VECTOR_DB_URL=http://localhost:6334

DATABASE_URL=sqlite://crates/shaide-db/schema.sqlite

WEBAPP_URL is optional: without it the server does not serve /app. It must be reachable from the server. just dev app and just stack app start the WebApp container and set it for you (http://localhost:3001 natively, http://webapp:8787 in compose); export WEBAPP_URL to point just dev at a WebApp you run yourself. Include any upstream base path in the URL: /app/assets/main.js is forwarded to <WEBAPP_URL>/assets/main.js.

Authentication

Users and admins exchange their username and password for a one-hour JWT:

curl -X POST http://localhost:8080/v1/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin-password"}'

Send the returned access_token to authenticated endpoints as Authorization: Bearer <access_token>.

Migrations

To create a new migration, you may do the following:

sqlx migrate add --source crates/shaide-db/migrations -r -s migration_name

To run the migrations:

cargo sqlx migrate run --source crates/shaide-db/migrations

And to revert a migration, you can:

cargo sqlx migrate revert --source crates/shaide-db/migrations

To run it locally, natively

cargo run # run the server
cargo run --bin shaide-cli -- list-users # list users with the cli. see the cli docs for more info

To build the container image

To build the container image, you have to run:

docker buildx build --tag shaide:{version} .

Before pushing the docker image to an external registry, retag it for the target registry, for example:

docker tag shaide:latest us-east5-docker.pkg.dev/your-gcp-project-id/proxy/shaide:{version}
docker push us-east5-docker.pkg.dev/your-gcp-project-id/proxy/shaide:{version}

To run the container locally

To run the built container image locally with Vertex AI as provider:

1. Authenticate with Google Cloud using your personal account:

gcloud auth application-default login

Alternatively you can also impersonate the service account, but for local development the personal account is recommended.

2. Run the container with:

docker run -p 8080:8080 \
    --add-host=host.docker.internal:host-gateway \
    -e GCP_API_KEY=$(gcloud auth application-default print-access-token) \
    -e ADMIN_PASSWORD={your-admin-password} \
    -e JWT_SECRET={your-jwt-secret-of-at-least-32-bytes} \
    -e SHAIDE_SERVER_UI_FQDN=dummy \
    -e SHAIDE_SERVER_UI_PORT=dummy \
    -e WEBAPP_URL=http://host.docker.internal:3001 \
    -v ~/.config:/root/.config \
    shaide:{version}

Notes:

• your-admin-password creates the initial admin user and is used to log in
• GCP_API_KEY is obtained from your authenticated Google Cloud session
• The dummy values for SHAIDE_SERVER_UI_FQDN and SHAIDE_SERVER_UI_PORT are required but not used when using Vertex AI
• The ~/.config:/root/.config volume mount provides access to the shaide server database

Docker compose

compose.yaml mirrors the k8s deployment and runs in one of two modes:

# Everything the shaide server depends on, to run the server natively
SHAIDE_SERVER_FQDN=host.docker.internal docker compose up -d
cargo run

# Every service in containers, the shaide server included
docker compose --profile server up -d --build

just dev and just stack wrap these. The webapp (app profile) and the MCP gateway (mcp profile) are optional: pass the profile names to the recipes, e.g. just dev app mcp, or --profile app to compose. When running the containerized server with the webapp, also set WEBAPP_URL=http://webapp:8787.

The containerized server is built from the dev Docker target, which adds azure-cli. It keeps its data in ~/.config/axem-docker, separate from the native server's ~/.config/axem, and reads a copy of ~/.azure (create the directory if you do not use Azure).

Images default to a local build of this repository and the released WebApp and Control Panel. To switch, set SHAIDE_SERVER_IMAGE, SHAIDE_WEBAPP_IMAGE or SHAIDE_CONTROL_PANEL_IMAGE, for example:

export SHAIDE_SERVER_IMAGE=ghcr.io/axem-solutions/shaide_server:v1.0.0
export SHAIDE_CONTROL_PANEL_IMAGE=shaide_control_panel:latest

Released server images are built from the runtime target and do not include azure-cli.

The Qdrant dashboard is available at http://localhost:6333/dashboard.

Stop everything with just services-down or docker compose --profile '*' down.

Documentation

To run the documentation:

cargo install mdbook
cd documentation
mdbook serve

Using just

To run commonly used commands, you can use just.

Available recipes:
    check                  # Run the same checks as CI
    db-migrate             # Apply all pending migrations
    db-new name            # Create a new migration
    db-prepare             # Regenerate SQLx offline query data
    db-revert              # Revert the latest migration
    db-shell [database]    # Open a SQLite database
    default                # Default recipe
    dev *profiles          # Start local dependencies and run the server natively
    docker-build [tag]     # Build a local server image
    services-down          # Stop every compose service
    services-up *profiles  # Start what a natively running server needs
    stack *profiles        # Run every service in containers, the server too

db-shell defaults to the server database under ~/.config/axem/shaide, and docker-build defaults to the image tag shaide-server:local.