finance/ENVIRONMENT_SETUP.md

Development Environment Setup Guide

Prerequisites

• Windows, macOS, or Linux
• Git
• Docker Desktop
• Visual Studio Code with Remote - Containers extension
• GitHub CLI

Initial Setup

1. Clone the Repository

   git clone https://github.com/acedanger/finance.git
   cd finance
   

2. Create Environment Files

   cp .devcontainer/.env.example .devcontainer/.env
   cp .env.example .env
   

GitHub Personal Access Token (PAT)

1. Create a new PAT:

   • Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
   • Click "Generate new token (classic)"
   • Name: finance-dev-token
   • Set expiration: 90 days (recommended)
   • Required scopes:
     • repo (Full control of private repositories)
     • read:packages (Download container images)
     • write:packages (Upload container images)
     • delete:packages (Optional: manage container versions)
     • workflow (GitHub Actions integration)

2. Configure the PAT:

   • Open .devcontainer/.env
   • Set GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

Building the Development Container

Using VS Code (Recommended)

1. Open the project in VS Code
2. When prompted, click "Reopen in Container"
   • Or press F1 and run "Dev Containers: Rebuild and Reopen in Container"

Using Command Line

1. Install the devcontainer CLI:

   npm install -g @devcontainers/cli
   

2. Build the container:

   devcontainer build .
   

3. Start the container:

   # With post-create command
   devcontainer up --workspace-folder .
   
   # Skip post-create command
   devcontainer up --workspace-folder . --skip-post-create
   

Building and Pushing the Container Image

1. Ensure you're in the .devcontainer directory

2. Choose your preferred script:

   Using PowerShell:

   .\build-and-push.ps1 your_github_username
   

   Using Git Bash/Unix Shell:

   chmod +x build-and-push.sh
   ./build-and-push.sh your_github_username
   

Both scripts perform the same functions:

• Validate prerequisites (Docker, GitHub CLI)
• Load GitHub PAT from .env file
• Build the container image
• Push to GitHub Container Registry
• Provide next steps for using the image

Environment Files

The project uses two separate environment files:

1. .devcontainer/.env:

   • Container-specific configuration
   • GitHub PAT
   • PostgreSQL settings
   • pgAdmin settings

2. .env:

   • Application-specific configuration
   • Development server port
   • API base URL
   • Node environment

Troubleshooting

Container Build Issues

• Ensure Docker Desktop is running
• Check that your PAT has the correct permissions
• Try rebuilding without cache: devcontainer build . --no-cache

GitHub Authentication Issues

• Verify your PAT in .devcontainer/.env
• Try logging in manually: gh auth login
• Check GitHub CLI status: gh auth status

Network Issues

• If DNS resolution fails, try using different DNS servers in devcontainer.json
• Check if GitHub Container Registry (ghcr.io) is accessible
• Verify Docker network settings

VS Code Issues

• Install/update the Remote - Containers extension
• Clear VS Code's container cache
• Check VS Code's "Dev Containers" output panel for detailed logs

Common Operations

Rebuilding the Container

# Using VS Code
F1 -> "Dev Containers: Rebuild Container"

# Using CLI
devcontainer build . --no-cache

Updating the Container Image

1. Make changes to Dockerfile or devcontainer.json
2. Run the build script:

   ./build-and-push.sh your_github_username
   

3. Update image reference in devcontainer.json
4. Rebuild container in VS Code

Starting Development Server

npm run dev