Skip to main content

Installation

This guide will walk you through installing Castlecraft Architect. For the quickest way to try the application, see the Quick Start with Docker Compose section below.

Prerequisites​

Before you begin, ensure you have the following installed:

  • Docker and Docker Compose: Required for the Quick Start method and other container-based setups. Visit the official Docker website to install.
  • Python: Version 3.11 or higher. You can check your Python version by running python --version or python3 --version.
  • pip: Python's package installer. This usually comes with Python. You can check by running pip --version or pip3 --version.
  • (Optional) Git: For cloning the repository if you plan to install from source or contribute.

Installation Methods​

This is the fastest way to get Castlecraft Architect running on your local machine to explore the UI and LLM-powered features.

1. Download Configuration Files

First, download the compose.yaml file from the official repository and create an environment file for your secrets.

curl -o compose.yaml https://gitlab.com/castlecraft/framework/architect/-/raw/main/deploy/compose.yaml
touch deploy.env

2. Configure Your Environment

You need to provide an API key for the LLM features. This example uses Google Gemini. Edit the deploy.env file you just created and add your key.

echo "GEMINI_API_KEY=your-gemini-key" >> deploy.env
echo "LITELLM_DEFAULT_MODEL=gemini/gemini-2.0-flash" >> deploy.env
  • Replace your-gemini-key with your actual Google Gemini API key.
  • You can optionally set GIT_REPO_URL_FOR_COMPONENTS in this file if you want Architect to clone and analyze an existing component repository.

3. Deploy and Access Architect

Now, start the services using Docker Compose.

docker compose --env-file deploy.env up -d

Once the containers are up, you can access the Castlecraft Architect web UI in your browser at http://localhost:8080.

Installing from Source (For Local Development and Contribution)​

To set up Castlecraft Architect for local development or to contribute to the project, you'll need to install it from the source code:

  1. Clone the repository:

    git clone https://gitlab.com/castlecraft/framework/architect
    cd architect

  2. Create and activate a virtual environment (Recommended):

    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate

  3. Install in editable mode: This allows you to make changes to the code and have them immediately reflected.

    pip install -e .

    If you are using uv (a fast Python package installer and resolver):

    uv pip install -e .

Projects scaffolded using cruft create https://gitlab.com/castlecraft/framework/architect (as described in the "Scaffolding Your First Project" guide) come with a pre-configured VS Code Devcontainer setup. This is the recommended way to develop your Architect-based application as it provides a consistent, isolated environment with all necessary services and tools.

The devcontainer uses Docker Compose to orchestrate services, including:

  • An architect service: Runs the actual backend application (e.g., on port 3000).
  • A development service: This is the container VS Code connects to, providing your Python environment and tools.

Steps to Use the Devcontainer:

  1. Prerequisites:

    • Docker Desktop installed and running.
    • Visual Studio Code installed.
    • The Dev Containers extension installed in VS Code.

  2. Scaffold Your Project: If you haven't already, create your project using cruft create https://gitlab.com/castlecraft/framework/architect.

  3. Open the Scaffolded Project in VS Code: Open the root folder of your newly scaffolded project (e.g., my_awesome_app/) in VS Code.

  4. Reopen in Container:

    • VS Code should automatically detect the .devcontainer/devcontainer.json file and show a notification in the bottom-right corner asking if you want to "Reopen in Container." Click it.
    • If you don't see the notification, you can open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and type/select "Dev Containers: Reopen in Container".

  5. Wait for the Container to Build/Start: The first time you do this, Docker will pull the necessary images and build the devcontainer. This might take a few minutes. Subsequent startups will be much faster.

Benefits of Using the Devcontainer:

  • Isolation: Your development environment is isolated from your host machine's configuration.
  • Consistency: Ensures all team members use the same environment and tool versions.
  • Pre-configured Services: The Architect backend and any other defined services (like a database in more complex setups) are automatically started and networked.
  • Integrated Tooling: VS Code extensions and settings specified in devcontainer.json are automatically available within the container.

Once VS Code has reopened in the container, your terminal, debugger, and all VS Code features will operate within the development service container. The architect application service will be running, and you can typically access it at http://localhost:3000 from your host machine's browser.

Advanced Docker Compose Setup (Collaboration/Production)​

While the Quick Start method is great for a trial, a more robust setup is needed for team collaboration or production deployment. This involves using a persistent database like PostgreSQL, connecting Architect to a Git repository for your components, and enabling authentication.

The same compose.yaml file used in the Quick Start is designed for this. You don't need to create a new file; you just need to provide a more detailed environment configuration.

1. Download Configuration Files

If you haven't already, download the compose.yaml file and create an environment file.

curl -o compose.yaml https://gitlab.com/castlecraft/framework/architect/-/raw/main/deploy/compose.yaml
touch deploy.env

2. Configure Your Environment for Production

The key difference for a production or collaboration setup is the set of environment variables you provide. Edit your deploy.env file to configure services like PostgreSQL, Git repository integration, and OIDC authentication. The compose.yaml file is pre-configured to use these variables to enable and connect the necessary services.

Example deploy.env for a collaboration setup:

# --- PostgreSQL Credentials (Required for Production) ---
# The compose.yaml will use these to connect to the postgres service.
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword
POSTGRES_DB=architect_prod_db

# --- Architect Components Git Repository (Required for Collaboration Mode) ---
# This is the repository containing your scaffolded application's components.
# The Architect container will clone this repo on startup.
GIT_REPO_URL_FOR_COMPONENTS=https://gitlab.com/your-group/your-scaffolded-app-repo.git
GIT_BRANCH_FOR_COMPONENTS=main

# --- Enable Production/Collaboration Features ---
# Use a persistent database connection string
SQL_ASYNC_CONNECTION_STRING=postgresql+asyncpg://${POSTGRES_USER:-architect_user}:${POSTGRES_PASSWORD:-architect_secret_password}@postgres:5432/${POSTGRES_DB:-architect_db}
# Enable authentication and authorization
FRONTEND_OIDC_ENABLED="true"
AUTHORIZATION_ENGINE=casbin

# --- OIDC Configuration (Required if FRONTEND_OIDC_ENABLED is "true") ---
ALLOWED_AUD=your_audience
CLIENT_ID=your_client_id
CLIENT_SECRET=your_client_secret
INTROSPECT_URL=https://your-oidc-provider.com/introspect
JWKS_URL=https://your-oidc-provider.com/.well-known/jwks
USERINFO_URL=https://your-oidc-provider.com/userinfo
OIDC_AUTHORITY=https://your-oidc-provider.com
OIDC_SCOPE="openid roles email profile phone"
OIDC_USERINFO_ROLES_CLAIM_NAME=your_roles_claim_name # e.g., architect_roles or roles

# --- LiteLLM (Optional - for LLM features) ---
# If using Gemini:
LITELLM_DEFAULT_MODEL="gemini/gemini-1.5-pro-latest"
GEMINI_API_KEY=YOUR_GOOGLE_GEMINI_API_KEY

# --- Redis Cache (Optional) ---
# To enable, uncomment the following line.
# CACHE_REDIS_URL="redis://redis:6379"

3. Review and Uncomment Services in compose.yaml (If Needed)

The downloaded compose.yaml may have optional services like redis or litellm-proxy commented out by default. Open the compose.yaml file and uncomment any services you have configured in your deploy.env file.

4. Deploy the Stack

Once your deploy.env is configured, start all the services.

docker compose --env-file deploy.env up -d

This command will start the Architect application along with PostgreSQL and any other services you have enabled. The Architect UI will be available at http://localhost:8080.

Configuration​

Castlecraft Architect uses a .env file for configuration, primarily for database connection settings.

  1. After installation (especially if installed from source), navigate to the project root.
  2. Create a .env file by copying the example if one is provided (e.g., .env.example). 
    cp .env.example .env
  3. Edit the .env file to set your database connection string. Architect supports PostgreSQL and SQLite via async SQLModel. Example for SQLite (default if no .env or DATABASE_URL is specified): 
    DATABASE_URL="sqlite+aiosqlite:///./architect.db"
    Example for PostgreSQL: 
    DATABASE_URL="postgresql+asyncpg://user:password@host:port/dbname"

Verifying the Installation​

Once installed, you can verify that Architect is working by running its help command or checking the version:

architect --help

Or:

architect version

This should display the help message or the installed version of Architect.

Deploying with Helm (Kubernetes)​

For deploying to Kubernetes, we provide a Helm chart that simplifies the management of all necessary components, including the Architect backend, frontend, PostgreSQL, and Redis.

Prerequisites​

  • A running Kubernetes cluster.
  • Helm installed on your local machine.

Installation Steps​

  1. Add the Castlecraft Helm repository: This command adds the project's GitLab Helm package registry as a new repository named architect.

    helm repo add architect https://gitlab.com/api/v4/projects/69478926/packages/helm/stable
    helm repo update

  2. Install the Architect chart: You must provide the URL to your components Git repository during installation. This is a critical step, as the backend service will clone this repository to load your application's logic.

    helm install my-architect-release architect/architect \
      --set architect.config.gitRepoUrlForComponents="https://gitlab.com/your-group/your-scaffolded-app-repo.git"
    • Replace my-architect-release with a name for your deployment.
    • Replace the gitRepoUrlForComponents with the actual URL to your scaffolded project's repository.

  3. Check the deployment status: After installation, Helm will print NOTES with commands to check the status and access your application.

For advanced configuration, you can download the default values.yaml file, customize it, and install the chart using helm install -f my-values.yaml my-architect-release castlecraft/architect.

Next Steps​

Explore how to manage your project's state and leverage LLMs with Architect in the Project State and LLM Context guide.