Skip to main content

Install via Docker Compose

Install App using Docker Compose.

Prerequisites​

Before you begin, make sure you have:

  • Docker ecosystem (Docker Engine, Docker CLI, Docker Compose).
  • A Docker Hub Personal Access Token (PAT) from Atlan
  • Object storage: AWS S3, Google Cloud Storage, or Azure Blob Storage with read/write permissions
  • Secret store access: AWS Secret Manager, Azure Key Vault, GCP Secret Manager, or HashiCorp Vault with read permissions

Generate client credentials​

OAuth client credentials are required for the App to authenticate successfully to the Atlan tenant. Follow these steps to generate client credentials:

  1. Generate the API token by following the steps in API access documentation.

  2. Create client credentials using the Atlan API.

  • Replace {{tenant}} with your Atlan tenant name

  • Replace <API token> with the token you generated in step 1

  • Replace {{App Name}} with your application identifier

    curl --location 'https://{{tenant}}.atlan.com/api/service/oauth-clients' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <API token>' \
    --data '{
      "displayName": "{{App Name}}-agent-client",
      "description": "Client for agent oauth for {{App Name}}",
      "scopes": ["events-app-permissions-scope","temporal-app-permissions-scope"]
    }'

    Example API response:

    {
      "clientId": "oauth-client-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "clientSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "createdAt": "1756112939595",
      "createdBy": "john.doe",
      "description": "Client for agent oauth for {{App Name}}",
      "displayName": "{{App Name}}-agent-client",
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "tokenExpirySeconds": 600
    }

Save the clientId and clientSecret values securely. You need these for the deployment configuration.

Prepare deployment environment​

Download the Docker Compose configurator binary and app-specific configuration file. The configurator is shared across all apps, while each app has its own configuration file.

  1. Use the Personal Access Token (PAT) provided by Atlan to authenticate with Docker Hub:

    docker login -u atlanhq
    # When prompted for password, enter the PAT provided by Atlan

    A "Login Succeeded" message confirms successful authentication.

  2. Create a directory for the deployment package:

    mkdir atlan-self-deployed-runtime
    cd atlan-self-deployed-runtime

  3. Download the Docker Compose configurator binary for your platform:

    • Linux AMD64:

      curl -O https://atlan-public.s3.amazonaws.com/apps/docker-compose-configurator-amd64.tgz
      tar -xvf docker-compose-configurator-amd64.tgz

    • Linux ARM64:

      curl -O https://atlan-public.s3.amazonaws.com/apps/docker-compose-configurator-arm64.tgz
      tar -xvf docker-compose-configurator-arm64.tgz

    • macOS ARM64:

      curl -O https://atlan-public.s3.amazonaws.com/apps/docker-compose-configurator-macos-aarch64.tgz
      tar -xvf docker-compose-configurator-macos-aarch64.tgz

    • macOS Intel:

      curl -O https://atlan-public.s3.amazonaws.com/apps/docker-compose-configurator-macos-intel.tgz
      tar -xvf docker-compose-configurator-macos-intel.tgz

    This command downloads and extracts the configurator tool for your platform.

  4. Download the app-specific configuration file:

    curl -O https://atlan-public.s3.amazonaws.com/apps/{app-package-name}.yaml

    Replace {app-package-name} with your app package name (for example, oracle-app).

  5. Optional Depending on organizational requirements, you may need to replicate images from Docker Hub to a private image repository. The specific steps vary by organization, here's one approach:

    • Pull the required connector image via Docker CLI:

      docker pull atlanhq/{app-image-name}:{app-image-tag}

      The command requires the same Docker Hub PAT from Atlan support that you used in step 1 for authentication

    • Push the image to your enterprise's registry. Note down the repository name and image tag generated.

Configure deployment settings​

  1. You see the following directories and files:

    ls
    • docker-compose-configurator-{platform}.tgz - Downloaded configurator archive (filename varies by platform)
    • docker-compose-generator/generate - Configuration tool binary
    • docker-compose-generator/config.yaml.sample - Sample configuration file template
    • {app-package-name}.yaml - Specific app configuration file

  2. Copy the sample configuration file:

    cp docker-compose-generator/config.yaml.sample config.yaml

  3. Edit config.yaml with your deployment settings using the sections below.

Configure general settings​

Follow these steps to edit the config.yaml file and update the details:

  1. Update Atlan tenant URL and app credentials:

    atlan:
      deployment_name: "agent"  # modify deploymentName as needed
      domain: "{tenant}.atlan.com"
      client_id: ""
      client_secret: ""
    • Replace "agent" with your desired deployment name.
    • Replace {tenant} with your Atlan tenant name.
    • Fill in the clientId and clientSecret values you generated in Generate client credentials section.

Configure object storage​

Self-Deployed Runtime needs a store for reading or writing files. Configure the object storage that matches your environment:

Did you know?

Dapr supports additional objects stores which aren't mentioned below. For more information, see Dapr object store documentation for other configurations.

  1. Locate the objectstore attribute in config.yaml.
  2. Add local file path configuration for Docker volume mounts.
objectstore:
  type: bindings.localstorage
  version: v1
  metadata:
    - name: rootPath
      value: "/data/storage"

Note: Mount a Docker volume to the specified path in your docker-compose.yml file. This is the recommended option for Docker and local development environments where files can be stored on the host filesystem. Example Docker Compose volume mount:

volumes:
  - ./data:/data/storage

Configure secret storage​

Self-Deployed Runtime fetches secrets from a secret store to connect to the source systems. The secret store references are used to configure the workflow. Configure the secret store that aligns with your security infrastructure:

Did you know?

Dapr supports additional secret stores which aren't mentioned below. For more information, see Dapr secret store documentation for other configurations.

  1. Locate the secretstore attribute in config.yaml.
  2. Add local file secret store configuration. For more information, see Local file secret store.
secretstore:
  type: secretstores.local.file
  version: v1
  metadata:
  - name: secretsFile
    value: [path to the JSON file]
  - name: nestedSeparator
    value: ":"
  - name: multiValued
    value: "false"

Note: Create a JSON file at the specified path containing your secrets in key-value format. Set appropriate file permissions and secure the file. This is the recommended secret store for Docker and local development environments.

Configure app-specific settings​

The app-specific YAML file ({app-package-name}.yaml) contains application metadata. You typically don't need to edit this file, but you can customize it if needed:

app_name: $APP_NAME # DO NOT EDIT `app_name`
app_image: $APP_IMAGE
app_port: 8000
  • app_name: Application identifier used by Atlan (do not modify)
  • app_image: Custom Docker image name (optional, only if using private registry)
  • app_port: Application port number (optional, defaults to 8000)

Deploy runtime​

Follow these steps to deploy secure App:

  1. Generate the required setup files:

    ./docker-compose-generator/generate --app {app-package-name}.yaml --config config.yaml

    Replace {app-package-name} with your app package name (for example, alloydb-postgres-app).

    This command generates the docker compose files in {app_name}-deployment directory by default. You can also provide the output directory using --output

  2. Start the deployment:

    cd {app_name}-deployment
    docker compose up -d

The deployment process typically takes a few minutes to complete depending on factors like network connectivity and image download time.

For more information on Docker Compose commands and configuration, see the Docker Compose documentation.

Verify app​

Follow these steps to verify the deployment:

Verify container status​

  1. Check container status:

    docker compose ps

    The output appears similar to:

    NAME                IMAGE                                    COMMAND                  SERVICE             CREATED             STATUS              PORTS
    {app-service-name}      atlanhq/{app-image-name}:{app-image-tag}   "/app/entrypoint.sh"   {app-service-name}      2 minutes ago       Up 2 minutes

    The container status shows Up indicating it's running successfully.

  2. Verify logs for the running container:

    docker logs {app-service-name} --tail=50 -f

    Look for these key log messages that confirm successful deployment:

    • Uvicorn running on http://0.0.0.0:8000 - Web server started
    • Workflow engine initialized - Workflow processing ready
    • dapr initialized. Status: Running - Dapr runtime active
    • Starting worker with task queue: atlan-{app-name}-DEPLOYMENT_NAME - Worker process started
    • GET /server/ready 200 - Health check endpoint responding

Verify registration via Atlan UI​

Once the App is successfully deployed, it communicates to the Atlan tenant and registers itself. Verify App registration is successful in Atlan:

  1. Sign in to your Atlan tenant as an administrator (for example, https://tenant-name.atlan.com).
  2. Navigate to Workflows > Agent.
  3. Search for your deployment name.
  4. Confirm the agent status shows as Active.

Agent registration and status takes a couple of minutes to reflect in Atlan UI

Next steps​