# Create a Github environment #### Before you begin In this section you will run the `yarn environment:init` script in **your forked infrastructure repository** which will help you to configure OpenCRVS environments. This command: * Creates GitHub environments * Drafts commands to bootstrap new servers * Prepare inventory files for ansible for environment provision * Prepares Helm chart values for deployment GitHub environments will host all secrets and variables required for successful infrastructure configuration (users, filesystem, kubernetes cluster, etc) and OpenCRVS deployment. Make sure you completed environment preparation steps and have all required information: | Property | Description | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GitHub Organisation | Own GitHub organisation with Team subscription. | | Country config repository | Refer to [Quick Start](/v2.0/technical/guides/installation/quick-start.md) | | Virtual machines (servers) created | [Preparation steps: ](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps.md)Verify you have IP addresses or DNS names for each environment and you are able to login on those VMs | | Domain names are registered | Verify [DNS](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/configure-dns.md) names are pointed to appropriate IP addresses of VMs. | | SSL Certificates issued or one of the available Let’s Encrypt is considered to be used | [Advanced Topics > TLS/SSL Config for Traefik](/v2.0/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik.md) | | Infrastructure repository forked | Refer to [Quick Start](/v2.0/technical/guides/installation/quick-start.md) | | GitHub Token with full code access and workflow permissions created | Personal access token (Fine grained token) with access to Country config and Infrastructure repositories. Refer to [Quick Start](/v2.0/technical/guides/installation/quick-start.md) | | DockerHub Account, token and repository are created | Make sure Country config image was built and pushed to DockerHub | | Users with their public keys to grant remote access to the servers | Refer to [Advanced Topics > SSH access](/v2.0/technical/guides/installation/advanced-topics/ssh-access.md) | | SMTP server configured | Refer to [Setup Infrastructure](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/setup-infrastructure.md) | | Optionally Third-party accounts created (sentry, slack, etc) | Refer to [prerequisite accounts](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/preparation-steps/create-prerequisite-accounts-and-repositories.md) | ### Create github environments Environments are managed by `yarn environment:init` script. The script will create files that must be pushed to Git, so it is **advisable to run the script in a new branch in order to open a pull request.** Re-run script for each environment: * development and (or) qa * staging * production {% hint style="info" %} *Migrating from an earlier version? ... Read the* [*Migration from Docker swarm guide.*](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/migration-from-docker-swarm-guide.md) Configuring a **staging** or **prodution** Github environment requires you to have a **backup server** environment in place. No explicit **backup** *Github* environment is created by this script anymore as of OpenCRVS v2.0. {% endhint %} To run the script, open terminal window and cd into your **forked infrastructure repository** and run the following command to start the configuration wizard: 
yarn install
yarn environment:init
{% hint style="info" icon="triangle-exclamation" %} You may notice that the same commands exist in an **infrastructure** folder in **forked countryconfig repo** but these exist only for backwards compatibility, e.g. OpenCRVS v1.8 or below and **should no longer be used**. Older installations should follow the [*Migration from Docker swarm guide*](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/migration-from-docker-swarm-guide.md) {% endhint %} You will be asked to provide values to configure key OpenCRVS components. Some actions can be automated and the script will guide you to the next steps. ### Environments init script questions #### Intro questions **Purpose for the environment?** The script will ask you to select the type of environment that you wish to create: ``` ? Choose a name and purpose for the environment? ❯ Development Quality assurance (no PII data) Staging (hosts PII data, no backups) Production (hosts PII data, requires frequent backups) Other... ``` Depending on your anwer different logic will be executed and some features might be not available. For example Approval workflow work only on environments with PII data. **What is the name of your environment?** Environment name is used later to create Kubernetes namespaces and other configuration objects like backup and restore folders. Environment name is read only property. We recommend you use following pre-configured environment names: * development * qa * staging * production #### GitHub **What is the name of your Github organisation?** Type your organisation. *Note that for personal repositories organisation is your GitHub login.* **What is your Github infrastructure repository?** Repository name where your infrastructure code lives. **What is your Github token?** Classic or Fine-grained token with access to infrastructure workflows and code. Once you provide answers to the questions script will connect GitHub: * If environment doesn't exist, script will continue it's execution

GitHub environment doesn't exist

* If environment exists, script will fetch information about existing secrets and variables for particular environment and repository.

GitHub environment already exists

* The script will fail if it cannot connect to Github for whatever reason. For environments with PII data script will ask you to answer additional questions: * `GH_APPROVERS`: Comma separated list of GitHub accounts responsible for Reviews and Approvals on OpenCRVS GitHub Actions workflows. This variable is defined at repository level. * `APPROVAL_REQUIRED`: Require approval for particular environment. This variable is defined at environment level. **It is strongly recommended to Approval requirement in production environments to mitigate the risk of accidental deployments or environment resets, which may lead to the deletion of citizen data.**

Configure production environment with required approval

#### Docker Hub The script will ask for your Dockerhub credentials or skip if they already exist. GitHub doesn't allow you to fetch secret values so you will not be able to check the current value, only updating the value is possible.

DockerHub credentials were created earlier

#### Kubernetes & Runtime The script will ask you to provide Kubernetes and Runtime options: * `DOMAIN`: Domain name to expose the OpenCRVS application frontend and APIs. It will be the domain after the subdomains that you configured when setting DNS. * `KUBE_API_HOST`: IP address or domain address for the Kubernetes master node. Provision script will generate Kubernetes config files for each user defined in users section of inventory file. * `WORKER_NODES`: (Options property) Comma separated list of additional Kubernetes cluster members (Virtual Machines). Leave empty for a single node setup. Worker nodes can be added later.

Only domain name was provided, Kubernetes cluster will be created with single node

#### SSH Users Script will ask you to create users with remote SSH access, answer following questions: * User name: Remote user name to login * Public ssh keys: Add public key(s) for remote login. Login by password is disabled by default, keys must be provided * Role: User role on remote system Check documentation for more examples and detailed instructions how to manage remote access: [Advanced topics > SSH Access](/v2.0/technical/guides/installation/advanced-topics/ssh-access.md) Once all the users are added, select **"Save & Exit"** in order to continue with the script.
#### Traefik SSL Certificate Installation script does configuration for traefik helm deployment. Following options are available at configuration time: 1. **Lets Encrypt certificate:** No additional input is required. The installation script will automatically configure Traefik to obtain and use Let’s Encrypt SSL certificates for you.\ **NOTE:** Your server must be accessible from the public internet for this process to work.\ This option is recommended only for testing and demonstration purposes, not for production environments. 2. **Static SSL certificate:** The script will prompt you to provide an SSL certificate and key for the frontend. The provided values will be securely stored as GitHub secrets. 3. **Custom configuration:** No additional questions will be asked. A preconfigured file (without the Let’s Encrypt section) is used, and Traefik will use its default certificate. Choose this option if you plan to configure Traefik yourself later using Helm chart values. Questions for **Static SSL certificate** * `SSL_CRT`: SSL Certificate or Certificate chain * `SSL_KEY`: SSL Certificate private keys Full documentation about traefik configuration can be found at: * Official documentation page: * [Advanced Topics > TLS/SSL Configuration for Traefik](/v2.0/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik.md) #### Storage {% hint style="info" %} **Only enable disk encryption if your data centre is equivalent to a Tier 2 or lower, where physical security may not be at its optimum.** If your data centre tier is higher, and extremely secure, there should be no need to encrypt the disk. **It is vital to safely store the encryption key** that is generated by the script to avoid loss of data. **Losing the encryption password is not recoverable.** {% endhint %} Disk Encryption: If disk encryption is enabled, provision GitHub Actions workflow will create encrypted file in the root (`/`) directory and mount it as `/data`. Disk encryption is optional. **Disk encryption can't be enabled later.** * `DISK_SPACE`: Amount of disk space that should be dedicated to OpenCRVS data (logs, monitoring and citizens crvs records). Specified value will become the size of an encrypted cryptfs `/data` directory. Specified disk space will be allocated on each cluster node for multi-node kubernetes cluster and this behaviour may change in the future. #### Backup Its possible for this environment to back up its data to another server e.g. backup every night. **It is strongly recommended if you are provisioning a production environment to enable backup.** * `BACKUP_HOST`: Backup server IP address or hostname. * `BACKUP_SERVER_USER`: User to connect to backup server. At this point you may choose any username, provision script will create user for you. E/g If you would like to use shared server to store backups from qa and production, you may want to have separate users for security reasons. Script will add backup host to ansible inventory files and configure appropriate values for helm release. Script will create private/public key-pair for backup server user. By default backup is configured to run at 01:00 AM by UTC, if you need to adjust backup schedule, update configuration manually at `environments//dependencies/values.yaml`

Backup configuration

More information about backup server configuration can be found at [Backup and Restore](https://github.com/opencrvs/documentation/blob/master/v2.0.0/setup/3.-installation/4.4-opencrvs-maintenance-tasks/4.3.7-backup-and-restore) section. #### Restore Its possible for this environment to restore backed-up data from another environment every night. **It is strongly recommended if you are provisioning a staging (pre-prod/mirror) environment to enable restore.** Restore configuration will ask you to provide the restore environment name from the existing environment list. **If the environment doesn't exist and will be created later, feel free to type future environment name here, but don't forget to create that environment BEFORE running OpenCRVS** [**dependencies**](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/deploy/running-a-dependencies-deployment.md) **deployment.** By default restore is configured to run at 00:00 AM by UTC, if you need to adjust the restore schedule, update configuration manually at `environments//dependencies/values.yaml`

Restore configuration

#### Databases & monitoring The script will proceed to ask you to set database and monitoring passwords. Strong passwords are suggested. It is advisable to accept the defaults presented to you. * `KIBANA_USERNAME`: (Default: opencrvs-admin): Kibana user name * `KIBANA_PASSWORD`: (Default: random value): Kibana password

Database and monitoring sections. In this example disk encryption is already enabled

#### Sentry `SENTRY_DSN`: The DSN tells the SDK where to send bug events to. OpenCRVS application has built-in Sentry support.
#### Metabase admin Metabase provides a public web interface to access an analytics editor. * `OPENCRVS_METABASE_ADMIN_EMAIL`: Metabase Admin user (only emails are allowed) * `OPENCRVS_METABASE_ADMIN_PASSWORD`: Metabase Admin password

Metabase configuratiob section

#### SMTP At this point smtp server should be configured. If you are using third-party email providers like Sendgrid, please make sure that your OpenCRVS domain is in whitelist and issued credentials are correct. * `SMTP_HOST`: Hostname or IP address of your smtp server * `SMTP_PORT`: Port where smtp server is listening * `SMTP_SECURE`: Use TLS for connection * `SMTP_USERNAME`: Username or email used to authenticate as a email client on smtp server * `SMTP_PASSWORD`: Password or API token depend on your email provider * `SENDER_EMAIL_ADDRESS`: All emails will be sent with this email in sender field * `ALERT_EMAIL`: Email address for alerting, this field is often used to integrate with Slack, Google Chart or any other corporate communication tool.

Email configuration

#### Review step Once all questions are answered, the script will generate strong database passwords for all the database technologies used in OpenCRVS. It will display all the secrets that the script will create and ask you if you want to continue to create the environment on Github. The script will slowly create the Github environment and upload all the secrets OpenCRVS requires to provision and deploy OpenCRVS from Github Actions. It will create Helm chart and values files ready for committing to your repository. On the final step the script will provide a command to bootstrap a self-hosted runner on your server. **Save the command from script output to a temporal file, you will need it later**. This is explained in the section [Bootstrap servers](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/bootstrap-servers.md): {% code title="Bootstrap command is automatically created ... " %} ``` curl -sfL https://raw.githubusercontent.com/opencrvs/infrastructure/refs/heads/develop/scripts/bootstrap/opencrvs-bootstrap.sh \ -o opencrvs-bootstrap.sh && \ bash opencrvs-bootstrap.sh --owner opencrvs \ --repo my-custom-infrastructure \ --env qa \ --token gh_PARSONAL_ACCESS_TOKEN \ --enable-runner ``` {% endcode %}

Command to bootstrap self-hosted runner on newly created virtual machine. Script will provide additional commands and hints for multi-node Kubernetes cluster and for configuration with backup server

Run following command on your infrastructure repository: ``` git status ``` You should get a number of files modified: ``` Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git restore ..." to discard changes in working directory) modified: .github/workflows/deploy-dependencies.yml modified: .github/workflows/deploy-opencrvs.yml modified: .github/workflows/github-to-k8s-sync-env.yml modified: .github/workflows/k8s-reindex.yml modified: .github/workflows/k8s-reset-data.yml modified: .github/workflows/k8s-seed-data.yml modified: .github/workflows/provision.yml modified: .github/workflows/reset-2fa.yml Untracked files: (use "git add ..." to include in what will be committed) environments/development/ infrastructure/server-setup/inventory/development.yml ``` Usually review is not required for files under the `.github` folder. Review modified files: * `infrastructure/server-setup/inventory/.yml`: Configuration file for Ansible playbook responsible for server provision. For more information please follow hints inside file and [SSH Access](/v2.0/technical/guides/installation/advanced-topics/ssh-access.md) section. * `environments/`: Folder with `values,yaml` files for helm charts: * `environments//traefik/values.yaml`: Update this file with proper configuration to handle SSL certificate. Please follow documentation under [TLS / SSL & DNS](/v2.0/technical/guides/installation/advanced-topics/tls-ssl-configuration-for-traefik.md) * `environments//opencrvs-services/values.yaml`: Review configuration and adjust according to your needs, **usually defaults are good for initial deployment** * `environments//dependencies/values.yaml`: Review configuration and adjust according to your needs, **usually defaults are good for initial deployment**. ### Final notice {% hint style="danger" %} The later [provision](broken://pages/VxyJDdy72Mi1awNbEQTu) script will disable password SSH access for all users on the server and create new users from the `infrastructure/server-setup/inventory/.yml` file. After provisioning, SSH will only be possible using public/private key pairs. {% endhint %} {% hint style="success" %} Users will be required to use Google Authenticator to SSH in after [provisioning](/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/provisioning-servers.md). This 2FA approach is an important step to secure your infrastructure. {% endhint %} {% hint style="danger" %} If any user is utilising the 1000 group, the script will fail. Modify your available user groups on the server to ensure this one is available. {% endhint %} {% hint style="danger" %} The .env.\ file outputted by this script contains sensitive information about your environment configuration. Copy the content of this file into a secure place or password manager such as [Bitwarden](https://bitwarden.com/) or [1Password](https://1password.com/) and delete this file. **YOU MUST NEVER SHARE THIS FILE, NOR COMMIT IT TO GIT!!!** This file is not required by OpenCRVS. {% endhint %} You will notice that an environment now exists in your Github repo containing all the secrets required. {% hint style="info" %} If you made a mistake and wish to run the script for this environment again, you must delete the environment on Github by clicking the trash icon first. **The environment and all secrets will be deleted and recreated, enforcing you to start over.** {% endhint %} **Repeat the process for all your required environments, e.g. qa, production, staging ...** Once all environments are setup, feel free to continue. --- # Agent Instructions: 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: ``` GET https://documentation.opencrvs.org/v2.0/technical/guides/installation/deploy-set-up-a-server-hosted-environment/create-a-github-environment.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.