io-growth

Getting Started

Using Devcontainer

The preferred way to setup your development environment is to use Devcontainer (Host system requirements).

Tip

If you are on macOS we recommend using Rancher Desktop configured to use VZ as Virtual Machine Type and virtiofs as volume Mount Type.

Visual Studio Code

1. Make sure docker is available and running in your host system
2. Install the Devcontainer Extension
3. Open the project root folder and select Dev Containers: Reopen in Container from the command palette
4. Visual Studio Code will build the devcontainer image and then open the project inside the container, with all the needed tools and extension configured

If you are on Windows and your network performs HTTPS inspection, Rancher Desktop can already trust the Windows root store while the Linux build used by Dev Container features still does not. In that case the build can fail with errors like dev-container-features/pre-commit_0 ... exit code: 60.

Automatic certificate export:

• initializeCommand always runs .devcontainer/scripts/export-devcontainer-ca.sh.
• On macOS and Linux, the script exits immediately with no changes.
• On Windows, the export is supported only from WSL or another environment with a POSIX shell, such as Git Bash, MSYS2, or Cygwin.
• In that case, the shell wrapper invokes the PowerShell exporter and writes the generated .crt files into .devcontainer/certs/.
• The generated certificates are ignored by git and installed in the devcontainer image before feature installation starts.
• If sh is not available on Windows, the export is skipped and the devcontainer prints a message that WSL or a POSIX shell is required.

The devcontainer includes the following services, started automatically via docker-compose:

Service	Image	Ports	Default credentials
PostgreSQL	postgres:17	5432	user: postgres, password: postgres, db: postgres
Azurite (Azure Storage emulator)	mcr.microsoft.com/azure-storage/azurite	10000 (blob), 10001 (queue), 10002 (table)	Default Azurite connection string
Redis	redis:7	6379	No auth enabled by default

Connection details are available inside the workspace container via environment variables (POSTGRES_HOST, POSTGRES_PORT, AZURITE_HOST, REDIS_HOST, etc.).

When you run an extra container from inside the devcontainer with docker run -p ..., the published port is exposed on the host Docker daemon, not on the workspace container's own localhost.

• From your local use http://localhost:<port>

Console

If you use a code editor that doesn't support Dev Container, you can still run it in your terminal.

1. Follow the instructions of the following chapter ("Using local machine") to setup your local environment
2. Run devcontainer from your terminal

pnpm devcontainer up --workspace-folder .
pnpm devcontainer exec --workspace-folder . /bin/bash

Using local machine

This project uses specific versions of node, pnpm and terraform. To make sure your development setup matches with production follow the recommended installation methods.

1. Install and configure the following tools in your machine

• nodenv - Node version manager
• tfenv - Terraform version manager
• terraform-docs - Generate Terraform modules documentation in various formats
• tflint - A Pluggable Terraform Linter
• pre-commit - A framework for managing and maintaining multi-language pre-commit hooks

2. Install node at the right version used by this project

cd io-growth
nodenv install

3. Build all the workspaces contained by this repo

pnpm build

Run ced-portal-be in Docker

From the repository root, build the image with the renamed workspace name and publish port 3000:

docker build -t ced-portal-be-local --build-arg APP_NAME=ced-portal-be .
docker run --rm -p 3000:3000 ced-portal-be-local

You can then call the health endpoint at GET /api/info:

• From your local: http://localhost:3000/api/info

Release management

We use changesets to automate package versioning and releases.

Each Pull Request that includes changes that require a version bump must include a changeset file that describes the introduced changes.

To create a changeset file run the following command and follow the instructions.

pnpm changeset

Useful commands

This project uses pnpm and turbo with workspaces to manage projects and dependencies. Here is a list of useful commands to work in this repo.

Work with workspaces

# build all the workspaces using turbo
pnpm build
# or
pnpm turbo build

# to execute COMMAND on WORKSPACE_NAME
pnpm --filter WORKSPACE_NAME COMMAND
# to execute COMMAND on all workspaces
pnpm -r COMMAND

# run the typecheck script on all workspaces
pnpm -r typecheck

Add dependencies

# add a dependency to the workspace root
pnpm -w add turbo

# add vitest as devDependency on citizen-func
pnpm --filter citizen-func add -D vitest

# add zod as dependency on each workspace
pnpm -r add zod

Folder structure

/apps

It contains the applications included in the project. Each folder is meant to produce a deployable artifact; how and where to deploy it is demanded to a single application.

Each sub-folder is a workspace.

/packages

Packages are reusable modules that implement a specific logic of the project. They are meant for sharing implementations across other apps and packages of the same projects, as well as being published in public registries.

Packages that are meant for internal code sharing have private: true in their package.json file; all the others are meant to be published into the public registry.

Each sub-folder is a workspace.

/infra

It contains the infrastructure-as-code project that defines the resources for the project as well as the execution environments. Database schemas and migrations are defined here too, in case they are needed.

/docs

Technical documentation about the project. Topics that may be included are architecture overviews, ADRs, coding standards, and anything that can be relevant for a developer approaching the project as a contributor or as an auditor.

User documentation doesn't usually go in here. For public packages, it must go in the package's README file so that it will also be uploaded to the registry; user-faced documentation websites, when needed by the project, go under the /apps folder as they are treated as end-user applications.

Releases

Releases are handled using Changeset. Changeset takes care of bumping packages, updating the changelog, and tagging the repository accordingly.

How it works

• When opening a Pull Request with a change intended to be published, add a changeset file to the proposed changes.
• Once the Pull Request is merged, a new Pull Request named Version Packages will be automatically opened with all the release changes such as version bumping for each involved app or package and changelog update; if an open Version Packages PR already exists, it will be updated and the package versions calculated accordingly (see https://github.com/changesets/changesets/blob/main/docs/decisions.md#how-changesets-are-combined). Only apps and packages mentioned in the changeset files will be bumped.
• Review the Version Packages PR and merge it when ready. Changeset files will be deleted.
• A Release entry is created for each app or package whose version has been bumped.

Folder structure

The IaC template contains the following projects:

repository

Set up the current repository settings. It's intended to be executed once on a local machine at project initialization.

cd infra/repository

# Substitute subscription_name with the actual subscription name if you selected Azure as CSP
az account set --name <subscription_name>

terraform init
terraform plan
terraform apply

Workflow automation

The workflow infra_plan.yaml is executed on every PR that edits the infra/resources folder or the workflow definition itself. It executes a terraform plan and comments the PR with the result. If the plan fails, the workflow fails.