.. _staging_sites: ============== Staging Sites ============== Crash reports --------------- Staging sites send crash reports to `GitLab Error Tracking `_ .. seealso:: :ref:`crash reports` in Logging documentation Deploying branches to staging ----------------------------- * Any branch can be deployed to the staging site by triggering one of the ``staging:`` CI jobs * To see status of the deployment, see `environments `_ page or its deploy job. * You can deploy branch and reset database at the same time by triggering a ``staging:reset`` job * It will fix any migration conflicts from previous deployment * it also deletes any data from database and re-populates it with the dummy data .. seealso:: | `Staging site index page `_ shows overview of staging sites and who currently uses them. | It also allows you to login with GitLab to deploy branches that have an associated merge request, reset database, or stop the site. Adding note ^^^^^^^^^^^^ You can add a note to the deployment by setting :envvar:`NOTE` in deployment job. The note will appear in the staging sites index page. It will be cleared the next time a deployment job is ran against that staging site. Stopping Staging Sites ----------------------- * You can manually stop a staging site by triggering the ``staging:stop`` CI job. * Staging sites automatically stop at the end of the day (21:00 UTC+0). * You can set a CI/CD variable called ``DAY`` before triggering ``staging:``. By setting the day, the staging site will automatically stop at the end of that day (21:00 UTC+0). To do this, follow these steps: 1. **Find and Click on the Desired Job**: Locate your pipeline and click on the job you want to run (e.g. `staging:alpha`). .. figure:: img/staging-jobs.png 2. **Set the Variable and Run the Job**: Set an environment variable called `DAY` as shown in the following image and click **Run job**. .. figure:: img/run-job.png If set correctly, you will see a 📌 next to the staging site in the `index page `_ after deployment. .. important:: | The format of the GitLab CI variable ``DAY`` should be only the day of the month, like **1**, **12**, **21**, **30**, etc. | The site will stop on that day, either in the current month or the next, depending on which comes first. | **For example:** | If you set ``DAY=10`` on **8th October**, the site will stop at the end of the day on **10th October**. | If you set ``DAY=1`` on **8th October**, the site will stop at the end of the day on **1st November**. Creating new Staging environments ---------------------------------- .. note:: These instructions are for Operations team members with access to Azure and the staging kubernetes cluster Staging site names follow letters `Greek alphabet `_, but additional special-purpose nam have a different name, depending on their purpose (e.g. "master"). Deploying a new staging site to cluster involves: #. Creating a new database on `staging postgres server `_ prefixed with "megforms-" #. Adding a new recordset to `azure.megsupporttools.com `_ and `staging.megit.com `_ domains #. Deploying the site to a new namespace in the `staging `_ kubernetes cluster .. code-block:: shell :caption: Snippet to create a new staging site. Assign ``NAME`` the name of the new site in all lowercase characters, with no spaces, for example ``omega``. export NAME= # Create database az postgres flexible-server db create --resource-group MatStaging --server-name matstaging-restored --database-name megforms-${NAME:?} # Add subdomains to DNS az network dns record-set cname create --resource-group meg --zone-name "azure.megsupporttools.com" --name "staging-${NAME:?}" az network dns record-set cname set-record --resource-group meg --zone-name "azure.megsupporttools.com" --record-set-name "staging-${NAME:?}" --cname staging.azure.megsupporttools.com az network dns record-set cname create --resource-group meg --zone-name "staging.megit.com" --name "${NAME:?}" az network dns record-set cname set-record --resource-group meg --zone-name "staging.megit.com" --record-set-name "${NAME:?}" --cname staging.megit.com # Deploy new site to a new namespace in kubernetes sh/create-region.sh ${NAME:?} Updating Staging environments ---------------------------------- When working on tasks that require interaction with external APIs, it's often necessary to provide an API key to the staging environment. This allows you to fully test the feature before it moves to production. The script below iterates through all namespaces in the staging environment and patches the megforms ConfigMap with the specified key-value pair. This ensures that the correct configuration is applied uniformly across the staging environment. .. code-block:: shell :caption: This snippet updates the ConfigMap in each namespace CONFIG_KEY= CONFIG_VALUE= namespaces=$(kubectl get namespaces --context staging -o jsonpath="{.items[*].metadata.name}") for namespace in $namespaces do kubectl --context=staging -n ${namespace} patch configmap megforms --patch "{\"data\": { \"${CONFIG_KEY:?}\": \"${CONFIG_VALUE:?}\" }}" done .. note:: Some built-in namespaces do not have a "megforms" configmap, which will result in the following error message: `Error from server (NotFound): configmaps "megforms" not found` However, this will not interrupt the loop, so all relevant namespaces will still be updated.