Skip to main content

Getting Started

This guide provides everything you need to set up a local development environment for Citadel.

Prerequisites​

  • Visual Studio Code
  • Docker Desktop
  • The VS Code Dev Containers extension

Local Setup​

The fastest way to get started is with the provided Dev Container.

  1. Clone the repository.

  2. Set up local configuration: Copy the example configurations for the Dev Container and VS Code workspace. This provides the necessary settings for running and debugging services.

    cp -r devcontainer-example .devcontainer
    cp -r vscode-example .vscode

  3. Configure Backing Services: Open .devcontainer/devcontainer.json. The dockerComposeFile array controls which services are started. To work on a specific service, you must enable its backing dependencies by uncommenting the relevant compose.*.yml files. For example, to work on the iam-service, you would uncomment its dependencies:

    // "compose.rauth.yml",
    // "compose.keycloak.yml",
    // "compose.mongo.yml",

    After uncommenting, your dockerComposeFile array would look like this:

    "dockerComposeFile": [
      "compose.core.yml",
      "compose.rauth.yml",
      "compose.keycloak.yml",
      "compose.mongo.yml",
      // ... any other services you need
    ],

  4. Open the project in VS Code and click "Reopen in Container" when prompted.

That's it! The environment will build, and all services will be started automatically.

Verifying the Environment​

Once the Dev Container is running, you can verify that all services have started correctly by checking the Docker containers.

Open a terminal in VS Code and run:

docker ps

You should see containers for iam-service, postgres, nats, and other core services.

Running Tests​

The monorepo is managed by Turborepo, which makes running tests simple.

To run all tests for all services from the root of the project, use:

pnpm run test

To run tests for a specific service (e.g., iam-service):

pnpm run test --filter=iam-service

Debugging a Service​

The Dev Container is configured for debugging. By copying the vscode-example directory, the pre-configured launch configurations are now available in the "Run and Debug" panel.

The process is similar for all services. For example, to debug the iam-service:

  1. Open a Go file in citadel/apps/iam-service.
  2. Set a breakpoint.
  3. Go to the "Run and Debug" panel in VS Code and select the "Debug iam-service" configuration.
  4. Press F5 to start debugging.

Making Your First API Call​

With the services running, you can interact with them via their REST APIs. The API Gateway exposes all services under the http://localhost:1111/api/ path.

As an example, here is how you can create a new tenant in the iam-service using curl:

curl -X POST http://localhost:1111/api/iam/tenants \\
-H "Content-Type: application/json" \\
-d '{"name": "My First Tenant"}'

You should receive a 201 Created response with the details of the newly created tenant, including its unique ID. This confirms that the iam-service and the database are working correctly.