> For the complete documentation index, see [llms.txt](https://jembi.gitbook.io/openhim-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://jembi.gitbook.io/openhim-platform/guides/provisioning-up-remote-servers/ansible.md).

# Ansible

## Platform Deploy

### Prerequisites

* Linux OS to run commands
* Install Ansible (as per <https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html>)
* Ansible Docker Community Collection installed
* ```bash
  ansible-galaxy collection install community.docker
  ```

### Infrastructure and Servers

Please see the `/inventories/{ENVIRONMENT}/hosts` file for IP details of the designated servers. Set these to the server that you created via Terraform or to an on-premises server.

### Ansible

#### SSH Access

To authenticate yourself on the remote servers your ssh key will need to be added to the `sudoers` var in the */inventories/{ENVIRONMENT}/group\_vars/all.yml*.

To have docker access you need to add your ssh key to the `docker_users` var in the */inventories/{ENVIRONMENT}/group\_vars/all.yml file*.

An authorised user will need to run the `provision_servers.yml` playbook to add the SSH key of the person who will run the Ansible scripts to the servers.

#### Configuration

Before running the ansible script add the server to your `known_hosts` file else ansible will throw an error, for each server run:

```
ssh-keyscan -H <host> >> ~/.ssh/known_hosts
```

To run a playbook you can use:

```bash
ansible-playbook \
  --ask-vault-pass \
  --become \
  --inventory=inventories/<INVENTORY> \
  --user=ubuntu \
  playbooks/<PLAYBOOK>.yml
```

**Alternatively**, to run all provisioning playbooks with the development inventory (most common for setting up a dev server), use:

```bash
ansible-playbook \
  --ask-vault-pass \
  --become \
  --inventory=inventories/development \
  --user=ubuntu \
  playbooks/provision.yml
```

#### Vault

The vault password required for running the playbooks can be found in the `database.kdbx` KeePass file.

To encrypt a new secret with the Ansible vault run:

```bash
echo -n '<YOUR SECRET>' | ansible-vault encrypt_string
```

> The **New password** is the original Ansible Vault password.

### Keepass

Copies of all the passwords used here are kept in the encrypted `database.kdbx` file.

{% hint style="info" %}
Please ask your admin for the decryption password of the database.kdbx file.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://jembi.gitbook.io/openhim-platform/guides/provisioning-up-remote-servers/ansible.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.