texastribune/base repository overview

⁠tt-docker-base

⁠Testing Dependabot PRs

Github's dependabot regularly creates PRs that bump package versions in order to fix known security issues. To ensure that these updates don't cause unexpected behavior on the Texas Tribune website, we prefer to test them locally before merging and deploying them.

Consult our dependabot testing guide⁠ for step-by-step instructions on testing and deploying.

⁠Updating dependencies

The following instructions provide a general guide to updating, adding or removing Python and Node dependencies in this repo.

⁠Setup

# bring down latest
git pull origin master

# create a feature branch for your changes
git checkout -b <new-branch-name>

⁠Add or Update Dependencies

⁠Python Dependencies

If you're adding or updating a python dependency:

1. Run a shell inside a container

      make base-shell
   

   Copy
2. Add or update python dependency

   # from inside the container shell from step 1:
   
   # add or upgrade a new production python dependency
   poetry add <package>
   
   # add/upgrade a new development dependency
   poetry add --dev <package>
   
   # pin the dependency to a specific version like this
   poetry add <package>@1.0.0
   

   Copy
3. Return to your local machine's shell

   exit
   

   Copy
4. Proceed to build and test locally⁠. Though recommended to use the poetry CLI, another way to accomplish the same is to edit pyproject.toml manually, then run poetry lock in the shell inside the container.

See the poetry docs⁠ for more commands and details on usage.

⁠Node Dependencies

If you're adding or updating a node dependency:

1. Run a shell inside a container

   make dev-shell
   

   Copy
2. Add or update node dependency

   # from inside the container shell from step 1:
   
   # enter the node directory
   cd node
   
   # add a new package
   npm install --save <package-name> # use --save-dev if dev dependency
   
   # add a specific version of a package
   npm install --save <package>@1.0.0
   
   # get help on npm for further usage
   npm help
   

   Copy
3. Return to your local machine's shell

   exit
   

   Copy
4. Proceed to build and test locally⁠.

⁠Build and Test New Images Locally

1. Build new images locally based on your python or node dependency updates

   # from your local machine's shell - not the container!
   
   make images
   

   Copy

   This creates two local images:

   • texastribune/base:<git-branch-name>-dev
   • texastribune/base:<git-branch-name>-base

   You can check that they were successfully created by runnning:

   docker images | $(git branch --show-current)
   
   # example output:
   texastribune/base          branchname-dev          2707ec0fcf6b        22 minutes ago      2.24GB
   texastribune/base          branchname-base         8a387eac996c        59 minutes ago      1.37GB
   
   

   Copy

2. Test it locally

   • Switch to your local texastribune repo:
     • Update the BASE_PRODUCTION_VERSION and BASE_DEVELOPMENT_VERSION variables
     • See texastribune docs for they should be updated, or use your text editor search.
   • Create a texastribune PR.

3. If all looks good, proceed to deploy steps⁠.

⁠Deploy

⁠Build the New Base Images

If this is a small change that's very unlikely to affect anyone else, you'll build your new images directly through master⁠, otherwise build your images through your feature branch⁠.

⁠Directly to Master Branch

1. Commit your changes to your tt-base branch.
2. Merge this branch into master and proceed to steps to deploy texastribune⁠.
3. Run the make bump command and follow the prompts in order to bump the version and tag it. The final prompt will push the tag to remote. There should be as little gap as possible between this step and the previous one so as to avoid conflicts with other committers.
4. Proceed to deploy to texastribune steps⁠.

⁠Through tt-base Feature Branch

1. Commit your changes to your tt-base branch.
2. Push your branch.
   • Docker Hub will build the images with the same name as when you built them locally⁠.
   • Now anyone can pull down and use the images texastribune/base:<git-branch-name>
   • Update your associated texastribune PR to use these ^ images built from the tt-base feature branch. Anyone can pull that PR's branch down to test locally.
   • You can check the status of the builds on Docker Hub⁠. You'll see a more accurate build log when logged-in under an account that is affiliated with the texastribune org in Docker Hub.
3. After the related texastribune PR is approved, merge your tt-base feature branch into master, and delete the feature branch.
4. git checkout master and git pull to get your local master branch even with remote.
5. Run the make bump command and follow the prompts in order to bump the version and tag it. The final prompt will push the tag to remote. There should be as little gap as possible between this step and the previous one so as to avoid conflicts with other committers.
6. Proceed to deploy to texastribune steps⁠.

⁠Deploy texastribune

1. Change your related texastribune PR to use the tag instead of the branch name (example: texastribune/base:1.2.14-base and texastribune/base:1.2.14-dev). See the texastribune README for the locations to change the version. You may want to wait until the Docker Hub build is complete before pushing your texastribune PR image version because the CI tests will fail if the image isn't available yet.
2. Make sure Docker Hub⁠ has built the image with the tag before deploying the texastribune PR. In an emergency you can leave in the branch name -- the image should already be built by Docker Hub and it won't go away even when the branch is deleted.
3. Merge related texastribune PR.
4. Deploy it
5. Your work is done.