Merge pull request #208 from cagov/devcontainer

Codespaces proof-of-concept

.devcontainer/devcontainer.json

@@ -0,0 +1,32 @@
+{
+    "name": "dbt",
+    "image": "mcr.microsoft.com/devcontainers/python:1-3.10-bookworm",
+    "features": {
+        "ghcr.io/devcontainers-contrib/features/poetry:2": {},
+        "ghcr.io/devcontainers/features/terraform:1": {}
+    },
+    "customizations": {
+        "vscode": {
+            "settings": {
+                "dbt.queryLimit": 50,
+                "git.allowNoVerifyCommit": true,
+                "python.defaultInterpreterPath": ".venv/bin/python"
+            },
+            "extensions": [
+                "innoverio.vscode-dbt-power-user"
+            ]
+        }
+    },
+    "secrets": {
+        "SNOWFLAKE_USER": {
+            "description": "Your Snowflake Username"
+        },
+        "SNOWFLAKE_PASSWORD": {
+            "description": "Your Snowflake Password"
+        },
+        "DBT_SCHEMA": {
+            "description": "The dev schema into which to build your dbt models (e.g. DBT_<YOURNAME>)"
+        }
+    },
+    "postCreateCommand": "poetry config virtualenvs.in-project true && poetry install && poetry run pre-commit install && mkdir -p ~/.dbt && cp .devcontainer/profiles.yml ~/.dbt"
+}

.devcontainer/profiles.yml

@@ -0,0 +1,14 @@
+dse_snowflake:
+  target: snowflake_dev
+  outputs:
+    snowflake_dev:
+      type: snowflake
+      account: heb41095
+      authenticator: username_password_mfa
+      user: "{{ env_var('SNOWFLAKE_USER') }}"
+      password: "{{ env_var('SNOWFLAKE_PASSWORD') }}"
+      role: TRANSFORMER_DEV
+      warehouse: TRANSFORMING_XS_DEV
+      database: TRANSFORM_DEV
+      schema: "{{ env_var('DBT_SCHEMA') }}"
+      threads: 4

.pre-commit-config.yaml

@@ -84,8 +84,8 @@ repos:
     hooks:
       - name: Dbt deps
         id: dbt-deps
-        language: python
-        entry: dbt deps --project-dir=transform
+        language: system
+        entry: poetry run dbt deps --project-dir transform
         always_run: false
         pass_filenames: false
         types: [sql]
@@ -103,7 +103,7 @@ repos:
     hooks:
       - id: sqlfluff
         name: sqlfluff
-        language: python
+        language: system
         description: "Lints sql files with `SQLFluff`"
         types: [sql]
         require_serial: true

docs/codespaces.md

@@ -0,0 +1,54 @@
+# Developing using Codespaces
+
+GitHub Codespaces allow you to spin up an ephemeral development environment in VS Code
+which includes a git repository, configurations, and pre-installed libraries.
+It provides an easy way for developers to get started working in a repository,
+especially if they are uncomfortable
+
+## Creating a Codespace
+
+Go to the "Code" dropdown from the main repository page,
+select the three dot dropdown, and select "New with options..."
+This will allow more configuration than the default codespace.
+
+![Create a new codespace](images/create-new-codespace.png)
+
+In the codespace configuration form, you will have an option to add "Recommended Secrets".
+This is where you can add your personal Snowflake credentials to your codespace,
+allowing for development against our Snowflake warehouse, including using dbt.
+You should only add credentials for accounts that are protected by multi-factor authentication (MFA).
+
+![Add codespace secrets](images/codespace-secrets.png)
+
+After you have added your secrets, click "Create Codespace".
+Building it may take a few minutes,
+but then you should be redirected to a VS Code environment in your browser.
+
+## Launching an existing Codespace
+
+Once your codespace is created, you should be able to launch it
+without re-creating it every time using the "Code" dropdown,
+going to "Open in...", and selecting "Open in browser":
+
+![Launch codespace](images/launch-codespace.png)
+
+## Using a Codespace
+
+Once you have created and configured a codespace,
+you have access to a relatively full-featured VS Code-based development environment.
+This includes:
+
+* An integrated bash terminal
+* dbt profiles configured
+* All Python dependencies for the project
+* All pre-commit hooks installed
+* git configured using your GitHub account
+
+### Usage notes
+
+1. When you launch a new codespace, it can take a couple of minutes for all of the extensions to install. In particular, this means that the Python environment may not be fully set-up when you land in VS Code. We recommend closing existing terminal sessions and starting a new one once the extensions have finished installing.
+1. The first time you make a commit, the pre-commit hooks will be installed. This may take a few minutes. Subsequent commits will take less time.
+1. If the pre-commit hooks fail when making a commit, it will give you the opportunity to open the git logs to view the errors. If you are unable to fix the errors for whatever reason, you can always make a new commit from the command line with `--no-verify`:
+    ```bash
+    git commit --no-verify -m "Your commit message"
+    ```

docs/setup.md

@@ -1,5 +1,8 @@
 # Repository setup
 
+These are instructions for individual contributors to set up the repository locally.
+For instructions on how to develop using GitHub Codespaces, see [here](./codespaces.md).
+
 ## Install dependencies
 
 ### 1. Set up a Python virtual environment

mkdocs.yml

@@ -27,16 +27,19 @@ markdown_extensions:
 nav:
   - Introduction: index.md
   - Project Setup: setup.md
+  - Codespaces: codespaces.md
   - Code Review: code-review.md
+  - Writing Documentation: writing-documentation.md
   - Naming Conventions: naming-conventions.md
   - Security Guidelines: security.md
   - Cloud Infrastructure: cloud-infrastructure.md
-  - dbt: dbt.md
-  - dbt Performance: dbt-performance.md
   - Snowflake: snowflake.md
   - Writing Documentation: writing-documentation.md
-  - dbt Snowflake Project: dbt_docs_snowflake/index.html
   - New Project Setup: new-project-setup.md
+  - dbt:
+      - Overview: dbt.md
+      - dbt Performance: dbt-performance.md
+      - dbt Snowflake Project: dbt_docs_snowflake/index.html
   - Data:
       - Building Footprints: data/footprints.md
   - Learning: