Using review instances to preview changes

If you need to do additional testing and verification outside of your local development environment, you can deploy changes from a branch or pull request. Review instances allow you to view changes to services or applications on the backend and frontend.

Reviewing visual or content changes to VA.gov

Review instances require access to the SOCKS proxy (docs: https://depo-platform-documentation.scrollhelp.site/getting-started/accessing-internal-tools-via-socks-proxy) , which means they cannot be reviewed by external stakeholders.

Review instances are created as part of a pull request for the vets-api, vets-website, or content-build GitHub repositories, but they can also be created manually by running a Jenkins job.

Screenshot of what the Review Instance link looks like. — Go to your Review Instance by clicking “View deployment” in your PR

Automatic creation

The Jenkins files in vets-website and vets-api define a stage that triggers a review instance deployment. Opening a PR will trigger the continuous integration (CI) process, which will generate a GitHub Deployment for the PR. A message on the PR will provide a link to the review instance.

Make sure your browser is configured to access the vetsgov-internal domain via the SOCKS proxy. See https://depo-platform-documentation.scrollhelp.site/getting-started/accessing-internal-tools-via-socks-proxy for detailed instructions.

Manual creation

If you made changes to branches in both vets-website and vets-api, and you want to test the changes together, you can manually trigger a build.

Visit http://jenkins.vfs.va.gov/job/deploys/job/vets-review-instance-deploy/ and log in.
Select "Build with Parameters."
Specify the branch names for api_branch and web_branch. These branches will be deployed together with the review instance.
When the process is completed, the URL for the review instance will be provided at the end of the output logs.

Access and usage

Review instances run on an independent virtual machine on which both vets-api and vets-website are installed. A nginx proxy in the front end directs requests. The web interface (vets-website) and API (vets-api) are available over HTTP behind the SOCKS proxy.

SSH

The review instances are accessible via SSH and you can modify code and see the changes. See

https://depo-platform-documentation.scrollhelp.site/getting-started/accessing-internal-tools-via-socks-proxy to set up SSH access.

Code is re-deployed on each commit which could result in lost changes local to the review instance.

To connect, retrieve the hostname of the instance:

Click the Deployed button in the GitHub deployment panel to open the Jenkins job.
Click Console output to view the provisioning task.
Search for Review instance available at on the page, which will give you the hostname string for SSH access.

Once you have the hostname, login with: ssh dsva@<hostname>

Common tasks

Both vets-website and vets-api processes are managed via Docker Compose. The code is stored in the dsva user's home directory. You might need to perform the following common tasks in a SSH session on the review instances.

vets-website

To view build and access logs for the development web server, enter the following command (enter Ctrl-C to exit):
cd ~/vets-website; docker-compose -f docker-compose.review.yml logs -f
This will include both build logs and access logs to the development web server running.
To rebuild vets-website after modifying the code, enter the following command:
cd ~/vets-website; docker-compose -f docker-compose.review.yml restart vets-website

You will not be able to view the instance while the website is building. The website will return 502 errors until the build process finishes and the server restarts. To check progress or troubleshoot if you suspect the build failed, use the command above to view logs.

To troubleshoot, start a shell session in the build environment using the following command:
cd ~/vets-website; docker-compose -f docker-compose.review.yml exec vets-website bash

vets-api

To force a restart of Puma or Sidekiq, enter the following command:
cd ~/vets-api; docker-compose -f docker-compose.review.yml restart vets-api
On review instances, Puma is running with RAILS_ENV=development, which enables live-reloading of some files, but not all. This means that you will not be able to see some code changes until you force a restart. The vets-api service in the compose file includes both Puma and Sidekiq.
To view stdout of Puma or Sidekiq processes, enter the following command (enter Ctrl-C to exit):
cd ~/vets-api; docker-compose -f docker-compose.review.yml logs -f vets-api
- Do not add -f if you only want to view the files one time.
- In development mode, vets-api does not log to stdout. It logs to log/development.log like it would on a local installation.
To rebuild the container and start over, enter the following command:
cd ~/vets-api; docker-compose -f docker-compose.review.yml down -v; docker-compose -f docker-compose.review.yml up -d
Running this command results in downtime for the instance.
To open a Rails console, enter the following command:
cd ~/vets-api; docker-compose -f docker-compose.review.yml exec vets-api bundle exec rails c
To get a bash shell in one of the containers, enter the following command:
cd ~/vets-api; docker-compose -f docker-compose.review.yml exec vets-api bash

Cleanup

The review instance is deleted when the non-main branch that a review instance is related to is deleted or when the instance is older than 7 days.

User authentication

The review instance requires a special nginx configuration that intercepts the callback to the staging-api.va.gov server, and forwards the authentication information to the appropriate review instance. The information is mapped by the RelayState parameter, which is provided to the review instance vets-api config with the REVIEW_INSTANCE_SLUG environment variable).

For implementation-specific details, see the revproxy nginx configuration.

Implementation details of Review Instances — Implementation details of the authentication for Review Instances

Help and feedback

Suggest content changes to this page.
Submit new Platform Website content.
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.