{"id":29881155,"url":"https://github.com/jonmatum/devcontainer-serverless-fullstack-template","last_synced_at":"2025-12-30T21:53:50.095Z","repository":{"id":306525507,"uuid":"1026475847","full_name":"jonmatum/devcontainer-serverless-fullstack-template","owner":"jonmatum","description":"Full-stack serverless template with DevContainers, FastAPI, React, DynamoDB, and Terraform for local-first development and AWS deployment","archived":false,"fork":false,"pushed_at":"2025-07-26T07:37:34.000Z","size":127,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-26T08:25:49.260Z","etag":null,"topics":["aws","cloud-native","devcontainers","dynamodb","fastapi","fullstack","infrastructure-as-code","lambda","local-development","react","serverless","template","terraform","vscode"],"latest_commit_sha":null,"homepage":"https://jonmatum.dev","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonmatum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-26T01:02:00.000Z","updated_at":"2025-07-26T07:37:38.000Z","dependencies_parsed_at":"2025-07-26T08:25:59.800Z","dependency_job_id":"161e1ecb-7cdc-45c6-b1d4-1f413bebf2d3","html_url":"https://github.com/jonmatum/devcontainer-serverless-fullstack-template","commit_stats":null,"previous_names":["jonmatum/devcontainer-serverless-fullstack-template"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/jonmatum/devcontainer-serverless-fullstack-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fdevcontainer-serverless-fullstack-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fdevcontainer-serverless-fullstack-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fdevcontainer-serverless-fullstack-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fdevcontainer-serverless-fullstack-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonmatum","download_url":"https://codeload.github.com/jonmatum/devcontainer-serverless-fullstack-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonmatum%2Fdevcontainer-serverless-fullstack-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268024950,"owners_count":24183154,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cloud-native","devcontainers","dynamodb","fastapi","fullstack","infrastructure-as-code","lambda","local-development","react","serverless","template","terraform","vscode"],"created_at":"2025-07-31T10:35:54.010Z","updated_at":"2025-12-30T21:53:50.057Z","avatar_url":"https://github.com/jonmatum.png","language":"Shell","readme":"# DevContainer Serverless Fullstack Template\n\nA modern, opinionated, and extensible DevContainer template built for cloud, full-stack, DevOps, and infrastructure developers. Easily reproducible, portable, and ready for work in seconds.\n\n## Key Features\n\n### Intelligent Project Initialization\n- **One-command setup** with `make init` - automatically configures your entire development environment\n- **Dynamic port management** - automatically finds and assigns available ports to prevent conflicts\n- **Smart dependency detection** - verifies prerequisites and sets up components intelligently\n- **Cross-platform compatibility** - works seamlessly on macOS, Linux, and Windows\n\n### Development Stack\n- **Shell Environment**: Zsh, Oh My Zsh, Powerlevel10k with syntax highlighting, autosuggestions, and opinionated configuration\n- **Cloud Tools**: AWS CLI v2, Terraform + tfswitch, OpenTofu v1.6.2\n- **Languages**: Node.js 20.11.1 (via nvm), Python 3.11.9 (via pyenv) with pipenv support\n- **Frontend**: React 19.0.0, Vite 6.3.4, TypeScript 5.7.2, ESLint 9.22.0\n- **Backend**: FastAPI with Python 3.11, Uvicorn server\n- **Quality Tools**: Pre-commit hooks with global configuration option\n- **Customizable Features**: Toggle each feature as needed with flags\n\n### Installed Tools\n`terraform`, `aws`, `node`, `npm`, `python`, `pip`, `pipenv`, `tofu`, `pre-commit`, `zsh`\n\n### DevContainer Features\nCustom features with configurable options:\n\n- **Shell Environment**: Zsh with Oh My Zsh, Powerlevel10k theme, autosuggestions with yellow highlighting, syntax highlighting, and opinionated configuration\n- **AWS CLI**: Version 2 with full AWS toolkit integration\n- **Terraform**: Latest version with tfswitch support\n- **Node.js**: Version 20.11.1 via nvm with npm package management\n- **Python**: Version 3.11.9 via pyenv with pipenv support enabled\n- **OpenTofu**: Version 1.6.2 for Terraform-compatible infrastructure management\n- **Pre-commit**: Global configuration enabled for consistent code quality\n\n### VS Code Extensions\nCurated, enterprise-grade extensions included (30 total):\n\n- **Cloud \u0026 Infrastructure**: `hashicorp.terraform`, `amazonwebservices.aws-toolkit-vscode`, `amazonwebservices.amazon-q-vscode`, `redhat.vscode-yaml`\n- **Python Development**: `ms-python.python`, `ms-python.vscode-pylance`, `ms-python.black-formatter`, `ms-python.isort`, `ms-toolsai.jupyter`, `ms-python.debugpy`\n- **Web Development**: `dbaeumer.vscode-eslint`, `esbenp.prettier-vscode`, `bradlc.vscode-tailwindcss`\n- **Shell \u0026 DevOps**: `timonwong.shellcheck`, `foxundermoon.shell-format`\n- **Containers**: `ms-azuretools.vscode-docker`\n- **Collaboration**: `eamodio.gitlens`, `donjayamanne.githistory`, `ms-vsliveshare.vsliveshare`, `github.vscode-github-actions`\n- **Documentation**: `bierner.markdown-mermaid`, `streetsidesoftware.code-spell-checker`\n- **Remote Development**: `ms-vscode-remote.remote-containers`, `ms-vscode-remote.remote-ssh`, `ms-vscode-remote.remote-ssh-edit`, `ms-vscode-remote.remote-wsl`, `ms-vscode-remote.vscode-remote-extensionpack`\n- **Productivity**: `visualstudioexptteam.vscodeintellicode`, `naumovs.color-highlight`, `ms-vscode.makefile-tools`\n\n## Quick Start\n\n### Method 1: Complete Setup (Recommended)\n\n1. **Clone this template:**\n   ```bash\n   gh repo create my-devcontainer --template jonmatum/devcontainer-serverless-fullstack-template --public --clone\n   cd my-devcontainer\n   ```\n\n2. **Initialize the project (IMPORTANT):**\n   ```bash\n   make init\n   ```\n   \n   This single command will:\n   - Check system prerequisites\n   - Scan and assign available ports automatically\n   - Configure DevContainer settings\n   - Set up frontend application with Vite + React\n   - Verify all components are properly configured\n\n3. **Start the development environment:**\n   ```bash\n   make up\n   ```\n\n4. **Open in VS Code:**\n   - Use `Dev Containers: Reopen in Container` from the Command Palette\n   - Your development environment is ready!\n\n### Method 2: Manual DevContainer Setup\n\n1. Clone the template\n2. Run `make init` to initialize the project configuration\n3. Open in Visual Studio Code\n4. Use `Dev Containers: Reopen in Container` from the Command Palette\n\n## Why `make init` is Essential\n\n### The Problem It Solves\n\nWithout proper initialization, you might encounter:\n- **Port conflicts** when multiple projects try to use the same ports (3000, 8000, etc.)\n- **Configuration mismatches** between DevContainer settings and actual services\n- **Missing dependencies** that cause services to fail silently\n- **Manual setup overhead** requiring multiple commands and configuration steps\n\n### What `make init` Does\n\n```bash\n\u003e\u003e Starting Complete Project Initialization\n\n[INFO]     Checking system prerequisites...\n[SUCCESS]  Prerequisites check completed\n\n[INFO]     Scanning for available ports...\n[SUCCESS]  Assigned ports: Frontend(3000) Backend(3001) Admin(3002) DynamoDB(3003)\n\n[INFO]     Rendering devcontainer configuration...\n[SUCCESS]  DevContainer configuration rendered\n\n[INFO]     Setting up frontend application...\n[SUCCESS]  Frontend application configured\n\n[INFO]     Verifying frontend setup...\n[SUCCESS]  Frontend verification passed\n\n[SUCCESS]  Project initialization completed successfully!\n```\n\n### Dynamic Port Assignment\n\nThe system intelligently manages ports to prevent conflicts:\n\n- **Automatic Detection**: Scans your system for available ports starting from 3000 (configurable via `PORT_START`)\n- **Conflict Resolution**: Uses `lsof` to detect port usage and automatically assigns next available port\n- **Service Mapping**: \n  - Frontend (React/Vite): First available port (FPORT)\n  - Backend (FastAPI): Second available port (BPORT = FPORT+1)  \n  - DynamoDB Admin: Third available port (APORT = BPORT+1)\n  - DynamoDB Local: Fourth available port (DPORT = APORT+1)\n- **DevContainer Sync**: Automatically updates `.devcontainer/devcontainer.json` with assigned ports\n- **Environment Variables**: Creates `.env` file with port assignments for consistent usage\n- **Hardcoded Forward Ports**: DevContainer forwards ports 3005-3008 by default\n\n### Port Assignment Example\n\n```bash\n# If ports 3000-3002 are busy, the system might assign:\nFRONTEND_PORT=3003   # React development server\nBACKEND_PORT=3004    # FastAPI server  \nADMIN_PORT=3005      # DynamoDB Admin interface\nDYNAMODB_PORT=3006   # DynamoDB Local database\n```\n\n### Benefits of Dynamic Port Management\n\n1. **Zero Configuration Conflicts**: Never worry about port collisions with other projects\n2. **Team Consistency**: Every developer gets the same relative port assignments\n3. **CI/CD Friendly**: Works in any environment without manual port configuration\n4. **Multi-Project Support**: Run multiple instances of this template simultaneously\n5. **Automatic Documentation**: Port assignments are clearly displayed and saved\n\n## Available Commands\n\nRun `make help` to see all available commands with detailed descriptions:\n\n```bash\nmake help      # Show comprehensive help with command categories\nmake status    # Display current project status and port assignments\nmake init      # Complete project initialization (recommended first step)\nmake up        # Start all containers\nmake down      # Stop all containers\nmake logs      # Follow container logs\nmake clean     # Clean up Docker resources\n```\n\n### Command Categories (24 total commands)\n\n- **Initialization \u0026 Setup**: Project initialization and configuration\n- **Component Setup**: Individual component management  \n- **Container Management**: Docker and container orchestration\n- **DevContainer Operations**: DevContainer CLI integration\n- **Maintenance \u0026 Cleanup**: System cleanup and maintenance\n- **Utilities \u0026 Diagnostics**: Debugging and validation tools\n\n### Project Status Monitoring\n\nUse `make status` to get a comprehensive overview of your project:\n\n```bash\n\u003e\u003e Project Status Report\n\nPort Configuration\n  Frontend:    3000\n  Backend:     3001\n  Admin:       3002\n  DynamoDB:    3003\n\nConfiguration Status\n  DevContainer: Configured\n  Environment:  Configured\n\nComponent Status\n  Frontend:    Initialized\n  Backend:     Available\n```\n\n## Full-Stack Integration Example\n\nThis template includes a complete full-stack integration example that demonstrates:\n\n### Counter Application Features\n- **Frontend**: React component with TypeScript that displays and manages a counter\n- **Backend**: FastAPI endpoints for counter operations with proper error handling\n- **Database**: DynamoDB Local for persistent storage\n- **Dynamic Port Discovery**: Frontend automatically discovers backend API endpoint\n- **Graceful Degradation**: Falls back to local state if backend is unavailable\n\n### API Endpoints\n\nThe backend provides RESTful endpoints for counter management:\n\n```bash\nGET    /api/counter     # Get current counter value\nPOST   /api/counter     # Increment counter (body: {\"increment\": 1})\nDELETE /api/counter     # Reset counter to zero\nGET    /              # Health check and API information\n```\n\n### Database Setup\n\nInitialize the database tables after starting the containers:\n\n```bash\nmake setup-db          # Create required DynamoDB tables\nmake check-db          # Verify database connection and tables\nmake reset-db          # Reset database (WARNING: deletes all data)\n```\n\n### Integration Architecture\n\n```\n┌─────────────────┐    HTTP/REST    ┌─────────────────┐    AWS SDK    ┌─────────────────┐\n│   React App     │ ──────────────\u003e │   FastAPI       │ ────────────\u003e │   DynamoDB      │\n│   (Frontend)    │                 │   (Backend)     │               │   Local         │\n│   Port: 3000    │ \u003c────────────── │   Port: 3001    │ \u003c──────────── │   Port: 8000    │\n└─────────────────┘    JSON         └─────────────────┘    boto3      └─────────────────┘\n```\n\n### Template Reusability Features\n\n**Dynamic Port Management**: The frontend automatically discovers the backend port using the template's port assignment pattern (frontend port + 1).\n\n**Environment Configuration**: All services use environment variables for configuration, making it easy to adapt for different environments.\n\n**Graceful Fallback**: The application works even if the backend is unavailable, demonstrating resilient design patterns.\n\n**AWS Best Practices**: The code structure follows AWS Lambda and API Gateway patterns, making it easy to deploy to production.\n\n### Customization Guide\n\nTo adapt this integration for your own use case:\n\n1. **Modify the Data Model**: Update `backend/scripts/setup_db.py` to create your tables\n2. **Add New Endpoints**: Extend `backend/app/main.py` with your business logic\n3. **Update Frontend**: Modify `frontend/app/src/App.tsx` to match your UI requirements\n4. **Environment Variables**: Add your configuration to `.env` and docker-compose.yml\n\n### Development Workflow\n\n```bash\n# 1. Initialize the project\nmake init\n\n# 2. Start all services\nmake up\n\n# 3. Set up the database\nmake setup-db\n\n# 4. Open in VS Code and start developing\n# The counter will persist across browser refreshes and container restarts\n```\n\n\n## Advanced Usage\n\n### Custom Port Range\nYou can specify a custom starting port:\n```bash\nPORT_START=4000 make init\n```\n\n### Quick Setup (Ports Only)\nFor faster setup when you only need port configuration:\n```bash\nmake init-quick\n```\n\n### Port Conflict Resolution\nIf you encounter port conflicts after initialization:\n```bash\nmake find-ports  # Reassign to new available ports\nmake check-ports # Check current port availability\n```\n\n### Configuration Validation\nVerify your setup is correct:\n```bash\nmake validate-config\n```\n\n### Component Management\nInitialize or reset individual components:\n```bash\nmake init-frontend   # Set up React frontend\nmake init-backend    # Set up FastAPI backend\nmake reset-frontend  # Reset frontend (removes app directory)\nmake reset-backend   # Reset backend (removes Pipfile)\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**Port conflicts during startup:**\n```bash\nmake check-ports  # Check which ports are in use\nmake find-ports   # Reassign to available ports\nmake up           # Restart with new ports\n```\n\n**DevContainer configuration issues:**\n```bash\nmake validate-config  # Verify all configurations\nmake init            # Reinitialize if needed\n```\n\n**Service not accessible:**\n```bash\nmake status  # Check service status and port assignments\nmake logs    # View container logs for errors\n```\n\n## Customization\n\nYou can modify `devcontainer.json` to:\n\n- Enable/disable features\n- Change tool versions\n- Add your own custom VS Code extensions\n- Modify container configurations\n\nThe Makefile system will automatically adapt to your changes while maintaining port management and initialization capabilities.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n\u003e echo 'Pura Vida \u0026 Happy Coding!';\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonmatum%2Fdevcontainer-serverless-fullstack-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonmatum%2Fdevcontainer-serverless-fullstack-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonmatum%2Fdevcontainer-serverless-fullstack-template/lists"}