{"id":20271015,"url":"https://github.com/postgres-ai/dle-se-ansible","last_synced_at":"2026-03-19T15:02:16.748Z","repository":{"id":114767881,"uuid":"598243578","full_name":"postgres-ai/dle-se-ansible","owner":"postgres-ai","description":"Ansible playbooks to manage DLE SE and EE installation, configuration, and upgrades","archived":false,"fork":false,"pushed_at":"2024-12-27T12:41:40.000Z","size":385,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-14T05:45:23.855Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postgres-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-06T17:49:19.000Z","updated_at":"2024-12-27T12:39:24.000Z","dependencies_parsed_at":"2024-11-06T19:18:28.905Z","dependency_job_id":"dd0be1a9-e059-4ba0-871a-a006eb57d92f","html_url":"https://github.com/postgres-ai/dle-se-ansible","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fdle-se-ansible","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fdle-se-ansible/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fdle-se-ansible/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgres-ai%2Fdle-se-ansible/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postgres-ai","download_url":"https://codeload.github.com/postgres-ai/dle-se-ansible/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241758954,"owners_count":20015249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T12:35:42.691Z","updated_at":"2026-03-19T15:02:16.742Z","avatar_url":"https://github.com/postgres-ai.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"## :rocket: `dle-se-ansible`: Automation of the DBLab Engine using Ansible.\n\nThis playbook deploys [DBLab Engine](https://gitlab.com/postgres-ai/database-lab) Standard Edition (DBLab SE) to any environment, cloud or on-prem.\n\nThe HowTo guide can be found here: [How to install DBLab Engine using the Postgres.ai Console](https://postgres.ai/docs/how-to-guides/administration/install-dle-from-postgres-ai).\n\n## Requirements\n\n- You will need the `Org key` and `Project name` from the [Postgres.ai platform](https://console.postgres.ai). These are provided by the platform upon registration. You can find more details [here](https://postgres.ai/docs/how-to-guides/administration/install-dle-from-postgres-ai).\n  - Keep in mind that without specifying these values in the `platform_org_key` and `platform_project_name` variables, the Ansible Playbook will not be executed.\n- For deployment on an existing server:\n  - Ubuntu 22.04 is currently a requirement (other versions Ubuntu and Debian might also work with some issues)\n  - Root privileges or sudo access\n  - Data storage disk (which is larger than the size of the database)\n- For deployment in one of the supported clouds:\n  - AWS: [Access key ID and secret](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html). Before performing automation, these values must be exported to the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` variables, respectively.\n  - GCP: [Service account](https://developers.google.com/identity/protocols/oauth2/service-account#creatinganaccount). Before performing automation, the contents of the service account JSON file must be exported to the `GCP_SERVICE_ACCOUNT_CONTENTS` variable. The service account requires the following IAM permissions:\n    - `compute.instances.*`, `compute.disks.*` — instance and disk management\n    - `compute.firewalls.create`, `compute.firewalls.update`, `compute.networks.updatePolicy` — needed to create an SSH access firewall rule for DBLab instances\n  - Digital Ocean: [Personal Access Token](https://docs.digitalocean.com/reference/api/create-personal-access-token/). Before performing automation, this token must be exported to the `DO_API_TOKEN` variable.\n  - Hetzner Cloud: [API Token](https://docs.hetzner.com/cloud/api/getting-started/generating-api-token/). Before performing automation, this token must be exported to the `HCLOUD_API_TOKEN` variable.\n- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) version 2.11.0 and higher, or a [Docker](https://docs.docker.com/engine/install/) on the computer from which the automation is performed.\n\n\n## Variables\n\n#### Cloud:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `provision` (optional) | Determines in which cloud to deploy the DBLab Engine server. Available values: `aws`, `gcp`, `azure`, `digitalocean`, `hetzner`, `none` (skip creating server resources). | `none` |\n| `server_name` (required) | The name of server to be created. | \"\" |\n| `server_type` (required) | The type of server to be created (the value depends on the selected cloud). | \"\" |\n| `server_image` (required) | The system image for the server to be created (the value depends on the selected cloud). | \"\" |\n| `server_location` (required) | The region in which the server will be created (the value depends on the selected cloud). | \"\" |\n| `server_network` (optional) | If specified, the server will be added to this network (must be created in advance). By default, the server is added to the default network (the value depends on the selected cloud). | \"\" |\n| `volume_size` (required) | The storage for `zpool_disk` (size in gigabytes). | \"\" |\n| `volume_type` (optional) | The volume type (the value depends on the selected cloud). Not applicable for Hetzner, DigitalOcean. | `gp3` for AWS, `pd-ssd` for GCP |\n| `ssh_key_name` (optional) | The name of the SSH key pre-uploaded to the cloud that will be added to the DBLab Engine server. If not specified, all ssh keys will be added (applicable for hetzner, digitalocean).  | \"\" |\n| `ssh_key_content` (optional) | if specified, the contents of the public key will be added to the cloud (for GCP - will be added to the server). | \"\" |\n| `state` (optional) | '`present`' to create or '`absent`' to delete server resources. | `present` |\n\nNote: if 'ssh_key_name' is not specified, with each new execution of the playbook, a new temporary SSH key is created (_automatically filling in the values of variables 'ssh_key_name' and 'ssh_key_content'_). To access the server during deployment. At the end of the deployment, the temporary SSH key is deleted.\n\n#### System:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `ssh_public_keys` (optional) | These SSH public keys will be added to the DBLab Engine server's to `~/.ssh/authorized_keys` file. Providing at least one public key is recommended to ensure access to the server after deployment. | \"\" |\n| `username` (optional) | The system user, owner of configuration files. | `root` |\n| `zpool_disk` (optional) | Disk for the ZFS pool (e.g.: /dev/sdb). If the specified disk is not empty, the playbook stops with an error (data deletion protection). If not specified, an attempt will be made to automatically detect an empty volume. | \"\" |\n| `zpool_name` (optional) | The name of the ZFS pool. | `dblab_pool` |\n| `zpool_mount_dir` (optional) | The path to mount the ZFS pool. | `/var/lib/dblab` |\n| `zpool_options` (optional) | Options used when creating a ZFS pool. | `-O compression=on -O atime=off -O recordsize=128k -O logbias=throughput` |\n| `zpool_datasets_number`(optional)  | The number of datasets that will be created for the ZFS pool. | `2` |\n| `zpool_datasets_name`(optional)  | Base name for ZFS datasets. Suffixes (01, 02, etc.) are appended based on `zpool_datasets_number`. | `dataset` |\n\n#### DBLab Engine:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `dblab_engine_version` (optional) | The DBLab Engine version. | `3.5.0` |\n| `dblab_engine_ui_version` (optional) | The DBLab Engine UI version.| `{{ dblab_engine_version }}` |\n| `dblab_engine_verification_token` (required) | The token that is used to work with DBLab Engine API. | `some-secret-token` |\n| `dblab_engine_base_path`(optional) | The directory containing the DBLab Engine directories and the configuration files. | `/root/.dblab` |\n| `dblab_engine_config_path`(optional) | The DBLab Engine 'configs' directory. | `{{ dblab_engine_base_path }}/engine/configs` |\n| `dblab_engine_meta_path`(optional) | The DBLab Engine 'meta' directory. | `{{ dblab_engine_base_path }}/engine/meta` |\n| `dblab_engine_logs_path`(optional) | The DBLab Engine 'logs' directory. | `{{ dblab_engine_base_path }}/engine/logs` |\n| `dblab_engine_dump_location`(optional) | The dump file will be automatically created on this location and then used to restore. (if 'logicalDump' job is specified in server.yml). | `{{ zpool_mount_dir }}/{{ zpool_name }}/dataset_1/dump` |\n| `dblab_engine_container_name` (optional) | The DBLab Engine container name. | `dblab_server` |\n| `dblab_engine_container_host` (optional) | The IP address at which the 'dblab_server' container accepts connections. | `127.0.0.1` |\n| `dblab_engine_container_default_volumes` (optional) | Directories to be mounted in the 'dblab_server' container. | (see `vars/main.yml`) |\n| `dblab_engine_container_additional_volumes` (optional) | Additional directories or files to be mounted in the 'dblab_server' container. | `[]` |\n| `dblab_engine_port` (optional) | The port at which the 'dblab_server' container accepts connections. | `2345` |\n| `dblab_engine_image` (optional) | The 'dblab_server' container image. | `postgresai/dblab-server:{{ dblab_engine_version }}` |\n| `dblab_engine_ui_image` (optional) | The dblab UI container image.  | `postgresai/ce-ui:{{ dblab_engine_ui_version }}` |\n| `dblab_engine_ui_port` (optional) | The port at which the dblab UI container accepts connections. | `2346` |\n| `dblab_engine_clone_access_addresses` (optional) | IP addresses, from which clone containers accepts connections. | `127.0.0.1` |\n| `dblab_engine_clone_port_pool.from` `dblab_engine_clone_port_pool.to` (optional) | Pool of ports for Postgres clones. Ports will be allocated sequentially, starting from the lowest value. The \"from\" value must be less than \"to\". | `6000`, `6099` |\n| `dblab_engine_config_file` (optional) | Copy the specified dblab configuration file instead of generating a new configuration file. | \"\" |\n| `dblab_engine_preprocess_script` (optional) | Copy the preprocessing script file to '`{{ dblab_engine_base_path }}/preprocess.sh`' | \"\" |\n\n\n#### Platform:\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `platform_project_name` (required) | Platform Project name. | \"\" |\n| `platform_org_key` (required) | Platform Organization key. | \"\" |\n\n#### DBLab CLI:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `cli_install` (optional) | Install the DBLab CLI on the dblab server. | `true` |\n| `cli_version` (optional) | The version of the DBLab CLI to be installed. | `{{ dblab_engine_version }}` |\n| `cli_environment_id` (optional) | an ID of the DBLab CLI environment to create. | `{{ platform_project_name }}` |\n\n#### Joe Bot:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `joe_bot_install` (optional) | Install Joe Bot. | `false` |\n| `joe_version` (optional) | The Joe Bot version.| `0.11.0-rc.4` |\n| `joe_config_path`(optional) | The Joe Bot 'configs' directory. | `{{ dblab_engine_base_path }}/joe/configs` |\n| `joe_meta_path`(optional) | The Joe Bot 'meta' directory. | `{{ dblab_engine_base_path }}/joe/meta` |\n| `joe_image` (optional) | The Joe Bot container image. | `postgresai/joe:{{ joe_version }}` |\n| `joe_container_name` (optional) | The Joe Bot container name. | `joe_bot` |\n| `joe_container_host` (optional) | The IP address at which the 'joe_bot' container accepts connections. | `127.0.0.1` |\n| `joe_port` (optional) | The port at which the 'joe_bot' container accepts connections. | `2400` |\n| `joe_platform_token`(optional) | Postgres.ai Platform API secret token. | `platform_secret_token` |\n| `joe_communication_type`(optional) | Available communication types (\"webui\", \"slack\", \"slackrtm\", \"slacksm\") | `webui` |\n| `joe_communication_signing_secret` (optional) | Web UI Signing Secret.  | `secret_signing` |\n| `joe_communication_slack_signing_secret` (optional) | Slack App Signing Secret.  | `secret_signing` |\n| `joe_communication_slack_access_token` (optional) | Bot User OAuth Access Token.  | `xoxb-XXXX` |\n| `joe_communication_slack_app_level_token` (optional) | App Level Token (for \"slacksm\").  | `xapp-XXXX` |\n| `joe_communication_channels_channel_id` (optional) | Web UI channel ID.  | `{{ platform_project_name }}` |\n| `joe_communication_channels_project` (optional) | Postgres.ai Platform project.  | `{{ platform_project_name }}` |\n| `joe_dblab_params_dbname` (optional) | PostgreSQL connection parameters used to connect Joe to the clone (dbname).  | `postgres` |\n| `joe_dblab_params_sslmode` (optional) | PostgreSQL connection parameters used to connect Joe to the clone (sslmode).  | `prefer` |\n| `joe_config_file` (optional) | Copy the specified Joe Bot configuration file instead of generating a new configuration file. | \"\" |\n\nNote: Joe Bot repository: https://gitlab.com/postgres-ai/joe\n\n\n#### Monitoring:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `netdata_install` (optional) | Install the Netdata (netdata-for-dle) with [plugin](https://gitlab.com/postgres-ai/netdata_for_dle) for DBLab Engine. | `true` |\n| `netdata_version` (optional) | The image tag of the 'netdata' container. | `1.40.1` |\n| `netdata_image` (optional) |  The image of the 'netdata' container. | `postgresai/netdata-for-dle:v{{ netdata_version }}` |\n| `netdata_port` (optional) |  The port at which the 'netdata' container accepts connections.  | `19999` |\n\n#### Proxy:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `proxy_install` (optional) | Install Envoy proxy and issue Let's Encrypt certificate. Used to provide public access to the dblab UI/API using an encrypted connection.  | `false` |\n| `proxy_version` (optional) | Version to install Envoy proxy. | `1.32` |\n| `proxy_dblab_engine_public_port` (optional) | The port on which the dblab UI is publicly accessible. | `443` |\n| `certbot_install_method` (optional) | Controls how Certbot is installed. Available options are 'package', 'snap', and 'pip'. | `pip` |\n| `certbot_install_version` (optional) | Certbot version (if 'certbot_install_method: pip'). | `2.6.0` |\n| `certbot_create_if_missing` (optional) | Set certbot_create_if_missing to yes or True to let this role generate certs. | `true` |\n| `certbot_create_method` (optional) | Set the method used for generating certs with the certbot_create_method variable — current allowed values are: standalone or webroot. | `standalone` |\n| `certbot_auto_renew`, `certbot_auto_renew_user`, `certbot_auto_renew_hour`, `certbot_auto_renew_minute` (optional) | By default, this role configures a cron job to run under the provided user account at the given hour and minute, every day. The defaults run certbot renew (or certbot-auto renew) via cron every day at 03:30:00. | `true`, `{{ username }}`, `3`, `30` |\n| `certbot_admin_email` (required) | Email to issue certificate, for example, `admin@example.com` | \"\" |\n| `certbot_domain` (required) | Domain to issue certificate, for example, `example.com` | \"\" |\n\n\nNote: More 'certbot' variables see [here](https://github.com/geerlingguy/ansible-role-certbot).\n\n#### Other:\n\n| Variable | Description | Default value |\n|:---------|:------------|:-------------:|\n| `print_usage_instructions` (optional) | Print the usage instructions after deployment.  | `true` |\n\n\n## Usage\n\n### Deployment\n\nNote: More detailed information about the deployment is available [here](https://postgres.ai/docs/how-to-guides/administration/install-dle-from-postgres-ai)\n\n\n#### Example of deployment in the Cloud (AWS) using a docker image\n\n```bash\nexport AWS_ACCESS_KEY_ID=*******\nexport AWS_SECRET_ACCESS_KEY=**********\n\ndocker run --rm -it \\\n  --env AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID} \\\n  --env AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY} \\\n  postgresai/dle-se-ansible:v1.1 \\\n    ansible-playbook deploy_dle.yml --extra-vars \\\n      \"provision='aws' \\\n      server_name='dblab-server' \\\n      server_type='m5.4xlarge' \\\n      server_image='ami-0620ab203b0c70bc0' \\\n      server_location='ca-central-1' \\\n      volume_size='200' \\\n      dblab_engine_verification_token='SMIgTlFeDdvs75Qg2GwfL18sCfyDf0O1' \\\n      dblab_engine_version='3.5.0' \\\n      zpool_datasets_number='3' \\\n      ssh_public_keys='ssh-ed25519 AAAAC*** alice.johnson@example.com' \\\n      platform_org_key='***********' \\\n      platform_project_name='dblab-server'\"\n```\n\n#### Example of deployment on a host using a docker image\n\nNote: Specify the username and IP address of your server in the `dblab_host` variable.\n\n```bash\ndocker run --rm -it \\\n  -v $HOME/.ssh:/root/.ssh:ro \\\n  -e ANSIBLE_SSH_ARGS=\"-F none\" \\\n  postgresai/dle-se-ansible:v1.1 \\\n    ansible-playbook deploy_dle.yml --extra-vars \\\n      \"dblab_host='root@12.34.56.78' \\\n      zpool_datasets_number='3' \\\n      dblab_engine_version='3.5.0' \\\n      dblab_engine_verification_token='super-secret-value' \\\n      platform_org_key='***********' \\\n      platform_project_name='dblab-server'\"\n```\n\nNote: In this example, we use `$HOME/.ssh:/root/.ssh:ro` to mount a directory with SSH keys to access the server from the container. You can override this value so that only a specific SSH key (example `$HOME/.ssh/my_key:/root/.ssh/id_rsa:ro`) is mounted into the container.\n\n### Management\n\n#### Configure a proxy for public access to the DBLab Engine UI/API server and clones:\n\n1. Start by configuring the `A` record of your domain so that it points to the public IP address of the DBLab Engine server.\n2. Define your domain in the `certbot_domain` variable and the email address in the `certbot_admin_email` variable.\n3. Execute the ansible-playbook with the `proxy` tag to install the Envoy proxy and to issue a Let's Encrypt certificate.\n\n```bash\ndocker run --rm -it \\\n  -v $HOME/.ssh:/root/.ssh:ro \\\n  -e ANSIBLE_SSH_ARGS=\"-F none\" \\\n  postgresai/dle-se-ansible:v1.1 \\\n    ansible-playbook software.yml --tags proxy --extra-vars \\\n      \"dblab_host='root@12.34.56.78' \\\n      proxy_install='true' \\\n      certbot_domain='example.domain.com' \\\n      certbot_admin_email='admin@example.domain.com' \\\n      platform_org_key='***********'' \\\n      platform_project_name='dblab-server'\"\n```\n\nNote: After you've set up your proxy server for clone access, you will need to specify the port by adding `+3000` to it in your connection string. For instance, if your regular connection port is `6000`, you should use port `9000` for accessing your clone. This adjustment is necessary to ensure proper network connectivity via proxy server.\n\n#### Configure a dblab server after deployment:\n\nBy default, every time the playbook is run, a new configuration file, named '`.dblab/engine/configs/server.yml`', will be generated. If you wish to manage the DBLab server via automation (for instance, to update the version or modify the configuration), you can specify a configuration file (e.g., located on the server where the playbook is initiated) in the `dblab_engine_config_file` variable. In this case, the content of this file will replace the configuration file. This can be particularly helpful for implementing CI/CD through your repository to manage the DBLab server.\n\n```bash\ndocker run --rm -it \\\n  -v $HOME/.ssh:/root/.ssh:ro \\\n  -v /path/to/config:/root/config:ro \\\n  -e ANSIBLE_SSH_ARGS=\"-F none\" \\\n  postgresai/dle-se-ansible:v1.1 \\\n    ansible-playbook software.yml --extra-vars \\\n      \"dblab_host='root@12.34.56.78' \\\n      zpool_datasets_number='3' \\\n      dblab_engine_version='3.5.0' \\\n      dblab_engine_config_file='/root/config/server.yml' \\\n      platform_org_key='***********' \\\n      platform_project_name='dblab-server'\"\n```\n\nNote: Replace '`/path/to/config'` with the actual directory path where your configuration file is located. This path will be mounted into the Docker container, allowing the automation to access your configuration file.\n\n#### Using Git for DBLab Engine configuration management\n\nExample of a repository that demonstrates a how to manage the configuration of the DBLab Engine using Git - https://gitlab.com/vitabaks/dblab-gitops-example\n\n## Support\n\nWith DBLab Engine installed from Postgres.ai Platform, guaranteed vendor support is included – [please use one of the available ways to contact](https://postgres.ai/contact).\n\n\n## Additional Resources\n\n- [How to install DBLab Engine from Postgres.ai Console](https://postgres.ai/docs/how-to-guides/administration/install-dle-from-postgres-ai)\n- [DBLab Engine repository](https://gitlab.com/postgres-ai/database-lab)\n- [DBLab CLI reference](https://postgres.ai/docs/reference-guides/dblab-client-cli-reference)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostgres-ai%2Fdle-se-ansible","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostgres-ai%2Fdle-se-ansible","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostgres-ai%2Fdle-se-ansible/lists"}