Instructions

Head to the staging website

Updating the website isn't as simple as merging to staging and then main. The servers for each environment must be manually updated and rebuilt to reflect those changes.

Staging is a required step before updating the main server.

Our staging server is an exact replica of the main website, providing a safe environment for developers to test and confirm everything works as expected under real-world conditions.

Skipping staging increases the risk of deploying broken or untested features to users.

The following are instructions on how to upload to the servers and a step-by-step on getting changes to users.

Prerequisites

• Changes must be reviewed and accepted before merging to staging.

• No issues/errors/bugs when running staging locally after merging and seeding.

• You'll need the login credentials from the "FreshAirKeyPass" keepass file under the title "Staging Server Login".

• If the VM runs out of space run docker system prune --all --force which will delete non running containers

Tools used: puTTY, GitHub, KeePass

1. Merging to Staging

Once your changes have been approved, merge the branch to staging as usual after resolving any merge conflicts.

Ensure that tests are passing and the Actions tab reports no issues.

2. Updating the Staging Server

Think of the staging server like a local clone of the repo on your PC. The changes you make on your clone don’t magically appear on someone else’s clone. The same goes for the server: you need to upload and apply your changes to the staging server for them to show up. The staging server is just a virtual computer after all.

The first step to updating the server is logging into it through puTTY. Input the staging IP address (in KeePass file) into the highlighted box and press Open.

A new puTTY terminal will open and ask for login details. The username and password are available in the KeePass file as well.

Once you've logged in, input the following commands:

cd ~
cd third-year-studio-2024-fresh-air/
git status                          # (Optional) this will tell you if the VM repo needs updating or not
git checkout staging                # (Optional) should already be in staging branch, but no harm in doing again
git pull
sudo docker ps                      # Displays list of running containers - should be 3 containers (DB, FE, BE)
sudo docker compose -f compose.production.yaml down
sudo docker compose -f compose.production.yaml build

When you first run sudo, you will be prompted to enter a password so enter the same one used to login.

After running the last command, you may have to wait a bit. If it takes longer than 10 minutes, request assistance from the Ops team. Previously, our issues had been resolved by removing all images and increasing RAM which is done by the Ops team.

Once built, run the following:

sudo docker compose -f compose.production.yaml up -d

This will start the servers with the new changes. If you don't build beforehand, the new changes will not be implemented.

3. Test Staging Website

Just because the changes merged cleanly and the server built successfully doesn’t mean the staging website is functional.

You still need to thoroughly test the staging site to confirm:

• The new features or fixes work as expected.

• No existing functionality has broken.

• Styling, layout, and performance are consistent.

• When running in staging branch in local environment, no issues occur when seeding and displaying site

Only after confirming staging is fully functional locally and through the URL should you move on to updating the main server.

4. Once Approved, Merge to Main

Once all new changes have been thoroughly tested and approved on the staging website and in the local environment, you can proceed to merge the staging branch into main.

Important:

Any changes made to the staging server’s configuration during testing must be mirrored on the main server before or during the deployment.

For example:

• If you increased the RAM on the staging server to fix errors, you’ll need to apply the same adjustment to the main server.

Remember: staging is a direct replica of our main (user-facing) product. Any issue that appears on staging is almost guaranteed to happen on main unless addressed.

Double-check both code and server settings before deploying to main.

Once confirmed, ensure the team is ready to rollout the whole release. You don't want to disrupt the user experience just for one minor change.

The team must let the users know that an update will occur soon and to expect the website to be down for a given period (up to 2hours). Ensure this notice is given well before the maintenance time.

Once that's done, follow the same steps in Step 2: Updating Staging Server but make sure you use the login credentials for the main server and not the staging server. Instead of "staging" use "main".

5. Testing Main

Once the main server has been rebuilt and is running, run through the same steps outlined in Step 3: Test Staging Website to ensure it works as intended.

Once confirmed, update all users that the website is up again and let them know about the new changes.

Deprecated

Updating the website using docker

To update the website in the VM for testing or production you will need to move into the third-year-studio-2024-fresh-air file by using the command

cd third-year-studio-2024-fresh-air

Once in this file you will need to make sure you are on the branch that you are wanting to work out of by using the command

sudo git checkout <your-chosen-branch>

( You will need to use sudo as you need permission in some files)

Once in the correct branch update the file by running the command

sudo git pull

Testing Site

To update the testing site you need to make sure to add tags to the frontend and backend images to display what you are testing e.g. if you are building the staging site the add the tag staging like so:

Once you have done this you will then need to run the commands

sudo docker compose -f compose.test.yaml build
sudo docker compose -f compose.test.yaml up -d

This will now build the images and create a new container that will display the changes on co2-app.testing.op-bit.nz

Live Site

To update the testing site you need to make sure to add tags to the frontend and backend images to display the main updated site the tag will be called main then add the tag staging like so:

Once you have done this you will then need to run the commands

sudo docker compose -f compose.production.yaml build
sudo docker compose -f compose.production.yaml up -d

This will now build the images and create a new container that will display the changes on co2-app.op-bit.nz. You will only need to the live site update once the changes you have done that sprint have been approved my the product owner.