mirror of
https://github.com/acedanger/finance.git
synced 2025-12-06 07:00:13 -08:00
a298de5af9
- Add build-and-push.ps1 script for Windows users - Update ENVIRONMENT_SETUP.md with cross-platform build instructions - Improve error handling and feedback in build scripts - Add proper Windows path handling Part of #29
155 lines
3.7 KiB
Markdown
155 lines
3.7 KiB
Markdown
# 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**
|
|
```bash
|
|
git clone https://github.com/acedanger/finance.git
|
|
cd finance
|
|
```
|
|
|
|
2. **Create Environment Files**
|
|
```bash
|
|
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:
|
|
```bash
|
|
npm install -g @devcontainers/cli
|
|
```
|
|
|
|
2. Build the container:
|
|
```bash
|
|
devcontainer build .
|
|
```
|
|
|
|
3. Start the container:
|
|
```bash
|
|
# 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:**
|
|
```powershell
|
|
.\build-and-push.ps1 your_github_username
|
|
```
|
|
|
|
**Using Git Bash/Unix Shell:**
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
./build-and-push.sh your_github_username
|
|
```
|
|
3. Update image reference in `devcontainer.json`
|
|
4. Rebuild container in VS Code
|
|
|
|
### Starting Development Server
|
|
```bash
|
|
npm run dev
|
|
``` |