### Install Dependencies and Run UI Locally

Source: https://docs.opentaco.dev/ce/local-development/ui

Installs project dependencies and starts the UI development server on a specified host and port.

```bash
cd ui
pnpm install   # or npm install
pnpm dev --host --port 3030
```

--------------------------------

### MySQL Example Connection

Source: https://docs.opentaco.dev/ce/state-management/query-backend

Example of setting environment variables for connecting to a MySQL database.

```bash
export TACO_QUERY_BACKEND=mysql
export TACO_MYSQL_HOST=mysql.example.com
export TACO_MYSQL_PORT=3306
export TACO_MYSQL_USER=taco_user
export TACO_MYSQL_PASSWORD=secure_password
export TACO_MYSQL_DBNAME=taco_production
export TACO_MYSQL_CHARSET=utf8mb4
```

--------------------------------

### PostgreSQL Example Connection

Source: https://docs.opentaco.dev/ce/state-management/query-backend

Example of setting environment variables for connecting to a PostgreSQL database.

```bash
export TACO_QUERY_BACKEND=postgres
export TACO_POSTGRES_HOST=my-postgres-server.example.com
export TACO_POSTGRES_PORT=5432
export TACO_POSTGRES_USER=taco_user
export TACO_POSTGRES_PASSWORD=secure_password
export TACO_POSTGRES_DBNAME=taco_prod
export TACO_POSTGRES_SSLMODE=require
```

--------------------------------

### Copy Environment Files for Docker Compose

Source: https://docs.opentaco.dev/ce/contributing/setup-dev-environment

Before starting Docker Compose, copy the example environment files to their active counterparts. This ensures all services have the necessary configuration.

```bash
cp self-hosting/docker-compose/orchestrator.env.example self-hosting/docker-compose/orchestrator.env
cp self-hosting/docker-compose/drift.env.example self-hosting/docker-compose/drift.env
cp self-hosting/docker-compose/sidecar.env.example self-hosting/docker-compose/sidecar.env
cp self-hosting/docker-compose/ui.env.example self-hosting/docker-compose/ui.env
```

--------------------------------

### MSSQL Example Connection

Source: https://docs.opentaco.dev/ce/state-management/query-backend

Example of setting environment variables for connecting to a Microsoft SQL Server database.

```bash
export TACO_QUERY_BACKEND=mssql
export TACO_MSSQL_HOST=sqlserver.example.com
export TACO_MSSQL_PORT=1433
export TACO_MSSQL_USER=taco_admin
export TACO_MSSQL_PASSWORD=secure_password
export TACO_MSSQL_DBNAME=taco_db
```

--------------------------------

### Start Docker Compose Services with Make

Source: https://docs.opentaco.dev/self-hosting/docker-compose

Use Make targets to start specific services or the entire OpenTaco stack. Ensure external databases and object storage are provided when starting only application services.

```bash
# start only shared platform services (databases/object storage)
make platform-up

# start only OpenTaco application services
# (only when providing external databases/object storage)
make opentaco-up

# start everything
make all-up
```

--------------------------------

### Start the backend service with Go

Source: https://docs.opentaco.dev/ce/local-development/backend

Source the .env file to load environment variables, then run the main Go application. Alternatively, use 'make start'. The default port is 3000.

```bash
set -a; source .env; set +a
go run main.go              # or: make start
```

--------------------------------

### Start All Services with Docker Compose

Source: https://docs.opentaco.dev/ce/contributing/setup-dev-environment

Build and start all required services using the provided make command. This is the primary method for setting up the full development environment.

```bash
# from repo root
make -C self-hosting/docker-compose all-up

# or run from the compose directory
# cd self-hosting/docker-compose
# make all-up
```

--------------------------------

### Install Digger Helm Chart

Source: https://docs.opentaco.dev/ce/self-host/deploy-helm

Install the Digger backend Helm chart using the 'helm install' command, specifying your values.yaml file. After installation, verify that all pods are running.

```bash
helm install digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \
  --namespace digger \
  --create-namespace \
  --values values.yaml
```

```bash
kubectl get pods -n digger
```

--------------------------------

### Install Taco CLI on Linux (AMD64)

Source: https://docs.opentaco.dev/ce/state-management/aws-apprunner-quickstart

Download the Linux AMD64 binary, make it executable, and move it to a directory in your PATH. This is the most common installation for Linux.

```bash
curl -L https://github.com/diggerhq/digger/releases/download/taco/cli/v0.1.7/taco-linux-amd64 -o taco
chmod +x taco

sudo mv taco /usr/local/bin
```

```bash
mkdir -p ~/.local/bin
mv taco ~/.local/bin
# Add to PATH in your shell profile if not already there
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

--------------------------------

### Start Digger API Service and Apply Migrations

Source: https://docs.opentaco.dev/ce/self-host/deploy-binary

Download the Digger API binary, make it executable, apply database migrations using AtlasGo, and then start the Digger API service.

```bash
cd digger/backend
wget https://github.com/diggerhq/digger/releases/download/v<DIGGER_VERSION>/digger-api-<OS>-<CPU_ARCH> -C ./diggerapi
chmod +x ./diggerapi
atlas migrate apply --url $DATABASE_URL --allow-dirty
./diggerapi
```

--------------------------------

### Start ngrok Tunnel

Source: https://docs.opentaco.dev/ce/local-development/ui

Starts an ngrok tunnel to expose the local UI development server to the internet.

```bash
ngrok http 3030
```

--------------------------------

### Install Sandbox Sidecar Dependencies

Source: https://docs.opentaco.dev/self-hosting/e2b-setup

Navigate to the sandbox-sidecar directory and install its npm dependencies.

```bash
cd sandbox-sidecar
npm install
```

--------------------------------

### Install OpenTaco Platform Reference Chart

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Installs the optional platform reference Helm chart. This chart provides essential dependencies like Traefik, MinIO, and CloudNativePG.

```bash
helm upgrade --install opentaco-platform-reference \
  oci://ghcr.io/diggerhq/helm-charts/opentaco-platform-reference \
  --version 0.1.0 \
  -n opentaco
```

--------------------------------

### Development Quick Start (SQLite)

Source: https://docs.opentaco.dev/ce/state-management/query-backend

Run OpenTaco with the default SQLite backend for development. No additional configuration is needed.

```bash
# No configuration needed - SQLite is the default
./taco
```

--------------------------------

### Directory Structure Example

Source: https://docs.opentaco.dev/ce/howto/include-exclude-patterns

Illustrates a typical project directory structure with environment-specific folders and a shared modules directory.

```yaml
development/
  main.tf
production/
  main.tf
modules/
  shared_moduleA/
  dev_only_module/

```

--------------------------------

### Digger Action Inputs Example

Source: https://docs.opentaco.dev/ce/reference/action-inputs

This example shows the structure of inputs for the Digger action, including project name, drift detection slack notification URL, and cache dependencies.

```yaml
project:
  description: 'project name for digger to run in case of manual mode'
  required: false
  default: ''
drift-detection-slack-notification-url:
  description: 'drift-detection slack drift url'
  required: false
  default: ''
cache-dependencies:
  description: "Leverage actions/cache to cache dependencies to speed up execution"
  required: false
  default: 'false'
```

--------------------------------

### Complete Example Workflow

Source: https://docs.opentaco.dev/ce/state-management/rbac

A comprehensive workflow demonstrating the full process of setting up RBAC, from initialization to creating permissions, roles, and listing permissions for verification.

```bash
# 1. Initialize RBAC
taco rbac init

# 2. Create permissions
taco rbac permission create dev-access "Developer Access" "Access to dev environments" \
  --rule "allow:unit.read,unit.write,unit.lock:dev/*"

taco rbac permission create prod-read "Production Read" "Read-only access to production" \
  --rule "allow:unit.read:myapp/prod"

# 3. List permissions to verify
taco rbac permission list

# 4. Create roles
taco rbac role create developer "Developer" "Can access dev environments"
taco rbac role create viewer "Viewer" "Can view production states"
```

--------------------------------

### Production Quick Start (PostgreSQL)

Source: https://docs.opentaco.dev/ce/state-management/query-backend

Configure and run OpenTaco with a PostgreSQL backend for production environments. Ensure all required environment variables are set.

```bash
export TACO_QUERY_BACKEND=postgres
export TACO_POSTGRES_HOST=prod-db.example.com
export TACO_POSTGRES_USER=taco_prod
export TACO_POSTGRES_PASSWORD=$PROD_DB_PASSWORD
export TACO_POSTGRES_DBNAME=taco
export TACO_POSTGRES_SSLMODE=require

./taco
```

--------------------------------

### Install OpenTaco Umbrella Chart

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Install or upgrade the OpenTaco umbrella Helm chart using the specified OCI registry path.

```bash
helm upgrade --install opentaco \
  oci://ghcr.io/diggerhq/helm-charts/opentaco \

```

--------------------------------

### Setting up Terragrunt in CI/CD

Source: https://docs.opentaco.dev/ce/getting-started/with-terragrunt

Use `setup-terragunt: true` to let Terragrunt manage the Terraform binary installation internally. This is crucial for CI/CD environments.

```yaml
jobs:
  build:
    steps:
      - uses: dprint/actions/setup-terragrunt@v1
        with:
          setup-terragrunt: true
```

--------------------------------

### Install Taco CLI on Windows using Command Prompt

Source: https://docs.opentaco.dev/ce/state-management/aws-apprunner-quickstart

Instructions for downloading and installing the Taco CLI on Windows using the Command Prompt, including adding it to the PATH for the current session.

```cmd
# Download (you may need to use a browser for this step)
# Save the file from: https://github.com/diggerhq/digger/releases/download/taco/cli/v0.1.7/taco-windows-amd64.exe

# Create a bin directory in your user profile
mkdir "%USERPROFILE%\bin"

# Move the downloaded file
move "taco-windows-amd64.exe" "%USERPROFILE%\bin\taco.exe"

# Add to PATH (this adds for current session only)
set PATH=%PATH%;%USERPROFILE%\bin
```

--------------------------------

### Digger Action Outputs Example

Source: https://docs.opentaco.dev/ce/reference/action-inputs

This example demonstrates how to access the output of the Digger action, specifically the terraform output.

```yaml
outputs:
  output:
    value: ${{ steps.digger.outputs.output }}
    description: The terraform output
```

--------------------------------

### Copy Platform Reference Values File

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Alternatively, start with the platform reference values file if you deployed the platform reference chart.

```bash
cp helm-charts/opentaco/values.platform-reference.yaml values-opentaco.yaml
```

--------------------------------

### Complete Digger Configuration Example

Source: https://docs.opentaco.dev/ce/reference/digger.yml

A comprehensive example showcasing advanced Digger configurations, including project definitions with apply requirements, branch settings, workflow specifications, drift detection, and nested project generation. It also details workflow configurations for staging and production environments, including environment variables, plan/apply steps, and event triggers.

```yml
traverse_to_nested_projects: true
auto_merge: false
pr_locks: true
allow_draft_prs: false
apply_after_merge: false
comment_render_mode: basic
report_terraform_outputs: true
mention_drifted_projects_in_pr: false
disable_digger_apply_comment: false
disable_digger_apply_status_check: false
trusted_appIDs:
  - 41898282
respect_layers: false
reporting:
  ai_summary: false
  comments_enabled: true
dependency_configuration:
  mode: hard
projects:
  - name: prod
    dir: prod
    alias: production
    apply_requirements: [approved, mergeable, undiverged]
    branch: main
    workspace: default
    terragrunt: false
    opentofu: false
    pulumi: false
    pulumi_stack: ""
    workflow: prod
    workflow_file: digger_workflow.yml
    drift_detection: true
    layer: 0
    include_patterns: ["../modules/**"]
    exclude_patterns: []
    depends_on: []
    aws_role_to_assume:
      aws_role_region: us-east-1
      state: arn:aws:iam::123456789012:role/state-role
      command: arn:aws:iam::123456789012:role/command-role
    aws_cognito_oidc:
      aws_account_id: "123456789012"
      aws_region: us-east-1
      cognito_identity_pool_id: us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      session_duration: 3600
  - name: staging
    dir: staging
    branch: main
    workflow: staging
    include_patterns: ["../modules/**"]
    exclude_patterns: []
generate_projects:
  include: "../projects/**"
  exclude: "../.terraform/**"
  terragrunt: false
  blocks:
    - block_name: dev-block
      include: "dev/**"
      exclude: "dev/.terraform/**"
      workflow: dev
      workflow_file: digger_workflow.yml
      opentofu: false
      terragrunt: false
      include_patterns: []
      exclude_patterns: []
      aws_role_to_assume:
        aws_role_region: us-east-1
        state: arn:aws:iam::123456789012:role/state-role
        command: arn:aws:iam::123456789012:role/command-role
workflows:
  staging:
    env_vars:
      state:
        - name: TF_LOG
          value: trace
      commands:
        - name: TF_LOG
          value: trace
    plan:
      filter_regex: ""
      steps:
        - init:
          extra_args: ["backend-config=../backend.hcl"]
        - run: "echo hello world"
        - plan
    apply:
      filter_regex: ""
      steps:
        - run: "echo hello world"
          shell: zsh
        - init
        - apply:
          extra_args: ["-compact-warnings"]
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_pull_request_to_draft: []
      on_commit_to_default: ["digger apply"]
      skip_merge_check: false
  prod:
    env_vars:
      state:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_BACKEND_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_BACKEND_TF_SECRET__ACCESS_KEY
      commands:
        - name: AWS_ACCESS_KEY_ID
          value_from: PROD_TF_ACCESS_KEY_ID
        - name: AWS_SECRET_ACCESS_KEY
          value_from: PROD_TF_SECRET_ACCESS_KEY
    plan:
      steps:
        - run: "checkov -d ."
        - init
        - plan
    apply:
      steps:
        - run: "terraform fmt -check -diff -recursive"
          shell: zsh
        - init
        - apply
    workflow_configuration:
      on_pull_request_pushed: ["digger plan"]
      on_pull_request_closed: ["digger unlock"]
      on_commit_to_default: ["digger unlock"]

```

--------------------------------

### Manual Taco CLI Installation on Windows

Source: https://docs.opentaco.dev/ce/state-management/aws-apprunner-quickstart

Provides steps for manually downloading, renaming, and placing the Taco CLI executable in a PATH directory on Windows.

```text
1. Download `taco-windows-amd64.exe` from the [releases page](https://github.com/diggerhq/digger/releases?q=taco%2Fcli&expanded=true)
2. Rename it to `taco.exe`
3. Place it in a directory that's in your PATH (like `C:\Windows\System32` for system-wide access)
4. Or create a `bin` folder in your user directory and add it to your PATH
```

--------------------------------

### Install OpenTofu with Digger Action

Source: https://docs.opentaco.dev/onboarding/configuring-github-actions-workflow

Configures the Digger action to set up OpenTofu, specifying the version to be installed. This is the default IaC engine.

```yaml
- uses: diggerhq/digger@vLatest
  with:
    digger-spec: ${{ inputs.spec }}
    setup-opentofu: true
    opentofu-version: 1.10.3
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Start Docker Compose and Stop UI

Source: https://docs.opentaco.dev/ce/local-development/ui

Starts all Docker Compose services and then stops the UI service to allow for local UI development.

```bash
make -C self-hosting/docker-compose all-up
docker compose -f self-hosting/docker-compose/docker-compose.yml stop ui
```

--------------------------------

### Start Compose Baseline in Hybrid Mode

Source: https://docs.opentaco.dev/ce/local-development/overview

This command starts all services using Docker Compose, forming the baseline for hybrid development where individual services will be stopped and run from source.

```bash
# from repo root
make -C self-hosting/docker-compose all-up

# or from self-hosting/docker-compose
make all-up
```

--------------------------------

### Example CODEOWNERS File Entry

Source: https://docs.opentaco.dev/ce/howto/codeowners

This is an example entry for a CODEOWNERS file. It specifies that any changes to files within the 'prod' directory require a review from the '@ZIJ' team.

```plaintext
prod @ZIJ # ensure ZIJ is reviewer for any prod changes
```

--------------------------------

### Helm Commands for Digger Installation

Source: https://docs.opentaco.dev/ce/self-host/self-host-on-azure

Add the Digger Helm repository, update repositories, and install the `digger-backend` chart using a custom values file.

```bash
$ helm repo add digger <https://diggerhq.github.io/helm-charts/>
$ helm repo update
$ helm install mydigger digger/digger-backend -f mydigger.yml
```

--------------------------------

### Azure Setup with Terragrunt

Source: https://docs.opentaco.dev/ce/getting-started/with-terragrunt

This snippet demonstrates setting up Terragrunt with Azure OIDC authentication in a GitHub Actions workflow.

```yaml
name: Digger Workflow

on:
  workflow_dispatch:
    inputs:
      spec:
        required: true
      run_name:
        required: false

run-name: '${{inputs.run_name}}'

jobs:
  digger-job:
    runs-on: ubuntu-latest
    permissions:
      contents: write      # required to merge PRs
      actions: write       # required for plan persistence
      id-token: write      # required for workload-identity-federation
      pull-requests: write # required to post PR comments
      issues: read         # required to check if PR number is an issue or not
      statuses: write      # required to validate combined PR status

    steps:
      - uses: actions/checkout@v4
      - name: ${{ fromJSON(github.event.inputs.spec).job_id }}
        run: echo "job id ${{ fromJSON(github.event.inputs.spec).job_id }}"
      - uses: diggerhq/digger@vLatest
        with:
          digger-spec: ${{ inputs.spec }}
          setup-azure: true
          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
          setup-terragrunt: true
          terragrunt-version: 0.44.1
        env:
          GITHUB_CONTEXT: ${{ toJson(github) }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ARM_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
          ARM_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
          ARM_SUBSCRIPTION_ID: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
```

--------------------------------

### Install Terragrunt with OpenTofu using Digger Action

Source: https://docs.opentaco.dev/onboarding/configuring-github-actions-workflow

Configures the Digger action to set up Terragrunt and OpenTofu, specifying versions for both. Terragrunt handles Terraform binary installation internally.

```yaml
- uses: diggerhq/digger@vLatest
  with:
    digger-spec: ${{ inputs.spec }}
    setup-terragrunt: true
    terragrunt-version: 0.44.1
    # Also install one IaC engine with Terragrunt.
    # OpenTofu is the default recommendation:
    setup-opentofu: true
    opentofu-version: 1.10.3
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Start Digger Service with Docker Compose

Source: https://docs.opentaco.dev/ce/self-host/deploy-docker-compose

Command to start the Digger backend services defined in the docker-compose.yml file. This command will also run initial database migrations.

```bash
docker-compose up
```

--------------------------------

### Multi-environment Terragrunt Setup

Source: https://docs.opentaco.dev/ce/reference/terragrunt-parsing

Sets up Terragrunt projects for multiple environments with various parsing options. Includes autoPlan, cascadeDependencies, defaultApplyRequirements, and preserveProjects.

```yaml
generate_projects:
  terragrunt: true
  terragrunt_parsing:
    autoPlan: true
    autoMerge: false
    createParentProject: false
    ignoreDependencyBlocks: false
    cascadeDependencies: true
    defaultApplyRequirements: ["approved", "mergeable"]
    defaultWorkflow: terragrunt-workflow
    preserveProjects: true
```

--------------------------------

### Setup Infracost Action

Source: https://docs.opentaco.dev/ce/howto/using-infracost

Use the official setup-infracost action in your workflow file. Ensure your Infracost API key is set as a secret.

```yaml
- name: Setup Infracost
        uses: infracost/actions/setup@v2
        # See https://github.com/infracost/actions/tree/master/setup for other inputs
        # If you can't use this action, see Docker images in https://infracost.io/cicd
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}
```

--------------------------------

### AWS Setup with Terragrunt

Source: https://docs.opentaco.dev/ce/getting-started/with-terragrunt

This snippet shows the configuration for a GitHub Actions workflow to set up Terragrunt with AWS credentials.

```yaml
name: Digger

on:
  workflow_dispatch:
    inputs:
      spec:
        required: true
      run_name:
        required: false

run-name: '${{inputs.run_name}}'

jobs:
  digger-job:
    name: Digger
    runs-on: ubuntu-latest
    permissions:
      contents: write      # required to merge PRs
      actions: write       # required for plan persistence
      id-token: write      # required for workload-identity-federation
      pull-requests: write # required to post PR comments
      issues: read         # required to check if PR number is an issue or not
      statuses: write      # required to validate combined PR status
    steps:
    - uses: actions/checkout@v4
    - name: ${{ fromJSON(github.event.inputs.spec).job_id }}
      run: echo "job id ${{ fromJSON(github.event.inputs.spec).job_id }}"
    - name: digger run
      uses: diggerhq/digger@vLatest
      with:
        digger-spec: ${{ inputs.spec }}
        setup-aws: true
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        setup-terragrunt: true
        terragrunt-version: 0.44.1
      env:
        GITHUB_CONTEXT: ${{ toJson(github) }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Install Taco CLI on Linux (386)

Source: https://docs.opentaco.dev/ce/state-management/aws-apprunner-quickstart

Download the Linux 386 binary for Taco CLI. This is for older or specific 32-bit architectures.

```bash
curl -L https://github.com/diggerhq/digger/releases/download/taco/cli/v0.1.7/taco-linux-386 -o taco
```

--------------------------------

### Create Kubernetes Namespaces

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Creates the necessary namespaces for OpenTaco and Traefik. Ensure these namespaces exist before proceeding with chart installations.

```bash
kubectl create namespace opentaco
kubectl create namespace traefik
```

--------------------------------

### Install Taco CLI on Linux (ARM64)

Source: https://docs.opentaco.dev/ce/state-management/aws-apprunner-quickstart

Download the Linux ARM64 binary for Taco CLI. Ensure you have the correct architecture for your system.

```bash
curl -L https://github.com/diggerhq/digger/releases/download/taco/cli/v0.1.7/taco-linux-arm64 -o taco
```

--------------------------------

### Install Taco CLI on macOS

Source: https://docs.opentaco.dev/ce/state-management/aws-apprunner-quickstart

Download the macOS ARM64 binary for Taco CLI, make it executable, and move it to the system's binary directory.

```bash
curl -L https://github.com/diggerhq/digger/releases/download/taco/cli/v0.1.7/taco-darwin-arm64 -o taco
chmod +x taco
sudo mv taco /usr/local/bin
```

--------------------------------

### Deploy OpenTaco using Helm

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Use the Helm CLI to install the OpenTaco umbrella chart. Specify the chart version, a custom values file, and the target namespace.

```bash
helm upgrade --install opentaco ./charts/opentaco \
  --version 0.1.0-public \
  -f values-opentaco.yaml \
  -n opentaco
```

--------------------------------

### Digger Plan with Project Flag (Short Form)

Source: https://docs.opentaco.dev/ce/reference/comment-args

Example of using the short form '-p' flag to specify a project for the 'digger plan' command.

```bash
digger plan -p dev_vpc
```

--------------------------------

### Taco CLI Server URL Setup

Source: https://docs.opentaco.dev/ce/state-management/gcp-quickstart

When prompted by the taco CLI for a server URL, use the URL of your deployed Cloud Run service. This example shows the format of the URL to be entered.

```text
https://statesman-1234567890.us-central1.run.app
```

--------------------------------

### Start Statesman Service

Source: https://docs.opentaco.dev/ce/state-management/quickstart

Command to start the Statesman service in detached mode using Docker Compose.

```bash
docker-compose up -d
```

--------------------------------

### Verify Taco CLI Installation on Linux

Source: https://docs.opentaco.dev/ce/state-management/aws-apprunner-quickstart

Check if the Taco CLI is installed and accessible by running the help command.

```bash
taco --help
```

--------------------------------

### Install Terraform with Digger Action

Source: https://docs.opentaco.dev/onboarding/configuring-github-actions-workflow

Configures the Digger action to set up Terraform, specifying the version to be installed. Ensure the correct Terraform version is used.

```yaml
- uses: diggerhq/digger@vLatest
  with:
    digger-spec: ${{ inputs.spec }}
    setup-terraform: true
    terraform-version: 1.5.5
  env:
    GITHUB_CONTEXT: ${{ toJson(github) }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### Create GCP Service Account and Bind Policies

Source: https://docs.opentaco.dev/ce/gcp/federated-oidc-access

Create a service account that Workload Identity Federation will impersonate. Bind necessary IAM policies to grant the service account required permissions and allow federation.

```bash
gcloud iam service-accounts create test-wif \
--display-name="Service account used by WIF POC" \
--project
```

```bash
gcloud projects add-iam-policy-binding  \
--member='serviceAccount:test-wif@.iam.gserviceaccount.com' \
--role="roles/compute.viewer"
```

```bash
gcloud iam service-accounts add-iam-policy-binding test-wif@.iam.gserviceaccount.com \
--project= \
--role="roles/iam.workloadIdentityUser" \
--member="principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools/github-wif-pool/attribute.repository/PradeepSingh1988/gcp-wif"
```

--------------------------------

### Install Taco CLI to User Directory on Linux

Source: https://docs.opentaco.dev/ce/state-management/quickstart

Installs the Taco CLI to a user-specific directory, avoiding the need for sudo. Ensures the directory is added to the PATH.

```bash
mkdir -p ~/.local/bin
mv taco ~/.local/bin
# Add to PATH in your shell profile if not already there
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

--------------------------------

### Terraform Initialize and Apply

Source: https://docs.opentaco.dev/ce/state-management/cloud-backend

Standard Terraform commands to initialize the project and apply infrastructure changes using the configured OpenTaco backend.

```bash
terraform init
terraform plan
terraform apply
```

--------------------------------

### Start Digger Backend Service with Docker

Source: https://docs.opentaco.dev/ce/self-host/deploy-docker

Run the Digger backend Docker container using the specified environment file and map the necessary port. This command initiates the service and database migrations.

```bash
docker run --env-file .env -p 3000:3000 registry.digger.dev/diggerhq/digger_backend:latest
```

--------------------------------

### Backend .env essentials

Source: https://docs.opentaco.dev/ce/local-development/backend

Create a .env file in the backend directory with essential configuration variables. Adjust the database URL and ports as needed. Ensure DIGGER_INTERNAL_SECRET matches the UI's ORCHESTRATOR_BACKEND_SECRET.

```bash
DATABASE_URL=postgres://postgres:postgres-password-CHANGE_ME@localhost:5432/orchestrator?sslmode=disable
DIGGER_INTERNAL_SECRET=orchestrator-secret          # must match UI ORCHESTRATOR_BACKEND_SECRET
DIGGER_ENABLE_INTERNAL_ENDPOINTS=true               # enables /_internal/*
DIGGER_ENABLE_API_ENDPOINTS=true                    # enables /api/*
PUBLIC_BASE_URL=http://localhost:3000               # public URL used for GitHub app callbacks
INTERNAL_BASE_URL=http://localhost:3000             # internal backend URL
```

--------------------------------

### Permission Rule Examples

Source: https://docs.opentaco.dev/ce/state-management/rbac

Illustrates various formats for permission rules, including effects (allow/deny), actions (unit operations, RBAC management), and resources (wildcards, specific units, directories).

```bash
# Allow read/write access to all dev environments
allow:unit.read,unit.write:dev/*

# Allow full access to specific production unit
allow:unit.read,unit.write,unit.lock,unit.delete:myapp/prod

# Deny deletion of production units
deny:unit.delete:myapp/prod

# Allow RBAC management
allow:rbac.manage:*
```

--------------------------------

### Build and Publish Barebones Fallback E2B Template

Source: https://docs.opentaco.dev/self-hosting/e2b-setup

Run the script to build and publish the barebones fallback template. This template serves as a default if other specific templates are not found.

```bash
npx tsx templates/build-barebones.ts
```

--------------------------------

### Example Valid JSON Job Event

Source: https://docs.opentaco.dev/ce/troubleshooting/action-errors

This is an example of a valid JSON structure for the 'event' key within a Digger workflow, used to troubleshoot 'Failed to unmarshal job string' errors.

```json
"event": {
      "inputs": {
        "comment_id": "2083250779",
        "id": "EiUBxZHh0qXQ92PR",
        "job": "{\"projectName\":\"dev\",\"projectDir\":\".\",\"projectWorkspace\":\"default\",\"terragrunt\":false,\"commands\":[\"digger plan\"],\"applyStage\":{\"steps\":[{\"action\":\"init\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"},{\"action\":\"apply\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"}]},\"planStage\":{\"steps\":[{\"action\":\"init\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"},{\"action\":\"plan\",\"value\":\"\",\"extraArgs\":[],\"shell\":\"\"}]},\"pullRequestNumber\":9,\"eventName\":\"issue_comment\",\"requestedBy\":\"motatoes\",\"namespace\":\"diggerhq/demo-opentofu\",\"runEnvVars\":{\"DEFAULT_BRANCH\":\"main\",\"PROJECT_DIR\":\".\",\"PROJECT_NAME\":\"dev\",\"PR_BRANCH\":\"motatoes-patch-7\"},\"stateEnvVars\":{},\"commandEnvVars\":{},\"state_role_name\":\"\",\"command_role_name\":\"\",\"backend_hostname\":\"https://c1db-5-151-139-93.ngrok-free.app\",\"backend_organisation_hostname\":\"digger\",\"backend_job_token\":\"cli:f4bfd7a5-ec11-4d43-ab88-93d12674e1d7\"}"
      },
    }
```

--------------------------------

### Terraform Initialization Output

Source: https://docs.opentaco.dev/onboarding/remote-jobs

This output shows the process of initializing Terraform provider plugins, including reusing existing versions and installing new ones. It also indicates that the Terraform execution plan has been generated.

```bash
Initializing provider plugins...
- Reusing previous version of hashicorp/null from the dependency lock file
- Installing hashicorp/null v3.2.4...
- Installed hashicorp/null v3.2.4 (signed by HashiCorp)

Terraform has made some changes to the provider dependency selections recorded
in the .terraform.lock.hcl file. Review those changes and commit them to your
version control system if they represent changes you intended to make.

Terraform has been successfully initialized!

Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # null_resource.smoke_test will be created
  + resource "null_resource" "smoke_test" {
      + id = (known after apply)
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Plan complete
```

--------------------------------

### List Roles

Source: https://docs.opentaco.dev/ce/state-management/rbac

Lists all available roles to verify their configurations and assigned permissions.

```bash
taco rbac role list
```

--------------------------------

### Build and Publish Prebuilt E2B Templates

Source: https://docs.opentaco.dev/self-hosting/e2b-setup

Execute the script to build and publish all sandbox templates defined in the manifest file. This makes them available for use with OpenTaco.

```bash
npx tsx templates/build-all.ts
```

--------------------------------

### Digger CI Workflow Setup with Statesman

Source: https://docs.opentaco.dev/ce/state-management/digger-integration

Configure your Digger CI workflow to use a Terraform Enterprise token stored as a secret. This setup assumes Statesman is used for state management.

```yaml
- uses: hashicorp/setup-terraform@v3
  with:
    cli_config_credentials_hostname: '[[opentaco-public-base-hostname]]'
    cli_config_credentials_token: ${{ secrets.STATESMAN_TOKEN }}

- uses: diggerhq/digger@vLatest
  with:
    digger-spec: ${{ inputs.spec }}
    setup-aws: true
    setup-terraform: false
```

--------------------------------

### Copy Production Values File

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Start with the production default values file for OpenTaco configuration.

```bash
cp helm-charts/opentaco/values-production.yaml.example values-opentaco.yaml
```

--------------------------------

### Configure Individual Terragrunt Projects

Source: https://docs.opentaco.dev/ce/getting-started/with-terragrunt

List individual Terragrunt projects in your digger.yml for smaller setups.

```yaml
projects:
- name: dev
  dir: dev
  terragrunt: true
- name: prod
  dir: prod
  terragrunt: true
```

--------------------------------

### Configure Local UI Environment Variables

Source: https://docs.opentaco.dev/ce/local-development/ui

Sets up essential environment variables for local UI development, including public URLs, WorkOS credentials, and backend service endpoints.

```bash
# URLs
PUBLIC_URL=http://localhost:3030                            # replace with ngrok URL when exposing UI
ALLOWED_HOSTS=localhost,127.0.0.1                           # include ngrok hostname when exposing UI

# WorkOS (User Management)
WORKOS_CLIENT_ID=<your_workos_client_id>
WORKOS_API_KEY=<your_workos_api_key>
WORKOS_COOKIE_PASSWORD=<32+ random chars>
WORKOS_REDIRECT_URI=http://localhost:3030/api/auth/callback # replace with ngrok callback URL; must match WorkOS config
WORKOS_WEBHOOK_SECRET=<if using webhooks locally via tunnel>

# Backend
ORCHESTRATOR_BACKEND_URL=http://localhost:3000
ORCHESTRATOR_BACKEND_SECRET=orchestrator-secret   # matches backend DIGGER_INTERNAL_SECRET
ORCHESTRATOR_GITHUB_APP_URL=http://localhost:3000/github/setup  # or your app install URL

# Statesman
STATESMAN_BACKEND_URL=http://localhost:8080
STATESMAN_BACKEND_WEBHOOK_SECRET=statesman-secret  # matches OPENTACO_ENABLE_INTERNAL_ENDPOINTS

# Optional
DRIFT_REPORTING_BACKEND_URL=http://localhost:3001
DRIFT_REPORTING_BACKEND_WEBHOOK_SECRET=...
POSTHOG_KEY=...
```

--------------------------------

### Example Terraform Output with Sensitive Value

Source: https://docs.opentaco.dev/ce/howto/masking-sensitive-values

This Terraform output demonstrates a sensitive value that can be masked by the `filter_regex` configuration.

```terraform
output "filterme" {
  value = "example_secret: filterme: topsecret"
}
```

--------------------------------

### Initialize Terraform Project

Source: https://docs.opentaco.dev/ce/state-management/quickstart

Initialize your Terraform project, connecting to the OpenTaco cloud backend and downloading necessary provider plugins.

```bash
terraform init
```

--------------------------------

### Check Backend Readiness

Source: https://docs.opentaco.dev/ce/state-management/aws-fargate-ad-quickstart

Verify that the backend service is ready by curling the readyz endpoint. This command uses the CloudFront domain obtained earlier.

```bash
echo "https://$(terraform output -raw cloudfront_domain)/readyz"
```

--------------------------------

### GCP Artifact Registry and Cloud Run Deployment Script

Source: https://docs.opentaco.dev/ce/state-management/gcp-quickstart

This bash script automates the setup of Google Artifact Registry for Docker images and deploys to Cloud Run. It enables necessary GCP APIs, creates a Docker repository if it doesn't exist, and configures Docker authentication for the specified region.

```bash
#!/bin/bash
set -e

# Set your project ID
PROJECT_ID="YOUR_GCP_REPO"
GCP_REPO_NAME="STATESMAN_ARTEFACT_NAME"
GCP_REGION="us-central1"

echo "Setting up Artifact Registry for Statesman..."

# Enable all required APIs
echo "Enabling required GCP APIs..."
gcloud services enable artifactregistry.googleapis.com
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable containerregistry.googleapis.com

# Check if repository exists, create if it doesn't
if ! gcloud artifacts repositories describe $GCP_REPO_NAME --location=$GCP_REGION >/dev/null 2>&1; then
  echo "Creating repository..."
  gcloud artifacts repositories create $GCP_REPO_NAME \
    --repository-format=docker \
    --location=$GCP_REGION \
    --description="Repository for OpenTaco Statesman images"
else
  echo "Repository already exists $GCP_REPO_NAME, skipping creation..."
fi

# Configure Docker auth
gcloud auth configure-docker $GCP_REGION-docker.pkg.dev

```

--------------------------------

### Get Traefik Service Endpoint

Source: https://docs.opentaco.dev/self-hosting/kubernetes

Retrieve the external endpoint of the Traefik service in the 'traefik' namespace to configure DNS.

```bash
kubectl get svc traefik -n traefik
```

--------------------------------

### Configure Auth0 Environment Variables

Source: https://docs.opentaco.dev/ce/state-management/quickstart

Set these environment variables with your Auth0 domain, client ID, and client secret. Ensure the issuer URL has a trailing slash.

```bash
OPENTACO_AUTH_ISSUER=https://[[auth0 domain]]/ # trailing slash is IMPORTANT!
OPENTACO_AUTH_CLIENT_ID=[[auth0 client id]]
OPENTACO_AUTH_CLIENT_SECRET=[[auth0 client secret]]
```

--------------------------------

### Configure Single Workspace

Source: https://docs.opentaco.dev/ce/state-management/cloud-backend

Example of a Terraform cloud block specifying a single workspace for state management on your OpenTaco server.

```hcl
terraform {
  cloud {
    hostname = "your-opentaco-server.com"
    organization = "opentaco"
    workspaces {
      name = "my-workspace"
    }
  }
}
```

--------------------------------

### Get CloudFront Domain

Source: https://docs.opentaco.dev/ce/state-management/aws-fargate-ad-quickstart

Retrieve the CloudFront domain name after the initial Terraform apply. This domain is used for accessing your application.

```bash
terraform output -raw cloudfront_domain
```