Development Containers

Development containers provide a local environment setup option for Mac and Linux at Caktus. Alternatively, if you'd prefer a more customized experience, you'll likely want to follow the general Developer On-boarding docs instead.

Goals

Development containers will:

Use the same Python/Node/etc. versions as the deployed environment.
Install base and development Python/Node/etc. packages automatically without having to use homebrew, pyenv, nvm, etc.
Streamline database and media sync from staging environments to ease initial setup.
Provide aws-cli and kubectl tools so you can access deployed environments.
Allow Git pull, commit, and push from within the container if using VS Code devcontainer.

Prerequisites

To get started, make sure you have:

Git and SSH keys configured as documented in Generating a new SSH key.
Container runtime like Docker Desktop on Mac or Docker Engine on Ubuntu.
- BuildKit enabled to support features provided by BuildKit builder toolkit.
Quirks with local filesystem (bind) mounts on Linux

Inside a container on Linux, any mounted files/folders will have the exact same permissions as outside the container - including the owner user ID (UID) and group ID (GID). Because of this, your container user will either need to have the same UID or be in a group with the same GID. If your user does not have a UID of 1000 (run id in your terminal to check), then you should specify USER_UID and USER_GID in a .env file at the root of your repo:
```
USER_UID=1001
USER_GID=1001
```
See Add a non-root user to a container for more information.
Caktus AWS account and AWS Command Line Interface (AWS CLI) configured for your development projects.
(Optional) Visual Studio Code with the Remote Development extension pack. See Developing inside a Container for additional information.

Project Setup

A project's documentation is the canonical setup documentation. Please refer to your project docs for detailed setup instructions.

However, most projects should roughly follow this pattern:

Build and start dev container: Using the VS Code Command Pallete (⇧⌘P), select Dev Containers: Reopen in Container.

Install Python and Node requirements:

python3 -m venv /code/venv
make setup
npm install

Setup pre-commit: Insetall pre-commit to enforce a variety of community standards:
```
pre-commit clean
pre-commit install
```

Reset local database: Download copy of staging database and restore it locally:

inv staging aws.configure-eks-kubeconfig
inv staging pod.get-db-dump
dropdb --if-exists DATABASENAME && createdb DATABASENAME
pg_restore -Ox -d $DATABASE_URL < *.dump

Reset local media: Download copy of staging media:

mkdir -p /code/media && sudo chown -R appuser:appuser /code/media
inv staging aws.sync-media --sync-to local --bucket-path="media/"

Start dev server:: Start the Django development server:
```
python manage.py runserver 0.0.0.0:8000
```
Start Node dev server: Start the Node development server in a separate terminal:
```
npm run dev
```

Published ports

Containers are separate environments, so if you want to access a server, service, or other resource inside your container, you will need to either "forward" or "publish" the port to your host. Where possible, containers will publish ports according to Development Containers: Port Mappings to avoid collisions. You may temporarily forward a port as a fallback or workaround.

Troubleshooting

Bad configuration option: usekeychain

If you're on a Mac, you may see an error like this:

/home/appuser/.ssh/config: line 3: Bad configuration option: usekeychain
/home/appuser/.ssh/config: terminating, 1 bad configuration options
fatal: Could not read from remote repository.

This is due to a special config option available on the Mac ssh-agent. To allow the dev container ssh-agent to ignore it, add this line to the top of ~/.ssh/config:

IgnoreUnknown AddKeysToAgent,UseKeychain

An error occured setting up the container

If you're on a Mac, you may see an error like this:

Stop (69 ms): Inspecting container
Start: Run in container: /bin/sh
Start: Run in container: uname -m
Stop (91 ms): Run in container: /bin/sh
Shell server terminated (code: 126, signal: null)
unable to find user appuser: no matching entries in passwd file
Start: Run in container: cat /etc/passwd
Stdin closed!
Error: An error occurred setting up the container.

To fix it:

While on VSCode press command + shift + P on your keyboard Once the popup displays, select Rebuild and Reopen in Container Press command + shift + P Once the popup displays, select and Rebuild and Reopen in Container

Unix file permissions modes show in `git diff`

From this Stack Overlow post, git thinks that it can correctly set the executable bit on checked out files, but when it attempts to do so it doesn't work. When it then reads back the status of those files it looks like the executable bit has been deliberately unset.

Until we figure out why this occurs, you can tell git to ignore any executable bit changes on the filesystem:

git config core.filemode false

Last update: 2024-11-18