Vibecode Template

A template repository for remotely deployed Vibecode projects with Flask backend and React frontend.

Quick Start

New to this template? See SETUP.md for detailed instructions on setting up a new app from this template.

Deploying to a server? See DEPLOYMENT.md for step-by-step remote server deployment instructions.

Project Structure

.
├── backend/          # Flask Python backend
├── frontend/         # React + TypeScript + Vite frontend
├── .github/          # GitHub Actions workflows
├── docker-compose.yml # Docker Compose configuration
└── Makefile          # Development commands

Local Development

# Install dependencies
make install

# Run backend (terminal 1)
make run-backend

# Run frontend (terminal 2)
make run-frontend

• Frontend: http://localhost:5173
• Backend: http://localhost:5000

Deployment

Tailscale Setup (Recommended for PWA)

The app is configured to run on Tailscale network, which provides:

• Automatic HTTPS via Tailscale
• Access from any device on your Tailscale network
• PWA installation support

Setup Steps:

1. Get a Tailscale Auth Key:

   • Go to https://login.tailscale.com/admin/settings/keys
   • Create a reusable auth key with appropriate expiration
   • Copy the key (starts with tskey-)

2. Configure Environment:

   cp .env.example .env
   # Edit .env and add your TAILSCALE_AUTHKEY

3. Start the Application:

   make docker-build
   make docker-up

4. Find Your Tailscale Address:

   • Check the Tailscale admin console: https://login.tailscale.com/admin/machines
   • Or run: docker exec <container-name> tailscale status
   • Your app will be accessible at: http://<tailscale-hostname>:80 or via MagicDNS

5. Enable HTTPS (for PWA):

   • Option A: Use Tailscale's HTTPS (recommended)
     • Enable HTTPS in Tailscale admin console for your device
     • Access via https://<tailscale-hostname>:443
   • Option B: Use Let's Encrypt with certbot
     • Set up certbot in a separate container or on the host
     • Mount certificates and uncomment HTTPS config in nginx.conf

Note: All devices accessing the app must be on your Tailscale network.

Using Docker Compose (build locally, without Tailscale)

# Build and start
make docker-build
make docker-up

# Or directly
docker compose up -d

App available at http://localhost:3000

Using Pre-built Images

Images are automatically built and pushed to GitHub Container Registry on push to main.

# Pull and run
docker compose -f docker-compose.prod.yml up -d

Update the image names in docker-compose.prod.yml to match your repository.

Environment Variables

Variable	Description	Default
SECRET_KEY	Flask secret key	change-me-in-production
DATABASE_URL	Database connection string	sqlite:///app.db
TAILSCALE_AUTHKEY	Tailscale authentication key (required for Tailscale setup)	-
USE_HTTPS	Enable secure cookies (set to 'true' when using HTTPS)	true

Copy .env.example to .env and configure as needed.

Data Persistence

Docker volumes are used for persistent data:

• app-data - SQLite database

Makefile Targets

Command	Description
make install	Install all dependencies
make run-backend	Start Flask backend (port 5000)
make run-frontend	Start Vite dev server (port 5173)
make docker-build	Build Docker images
make docker-up	Start containers
make docker-down	Stop containers
make clean	Remove dependencies and build artifacts

Getting Started

1. Clone this repository
2. Update project-specific configuration:
   • Update docker-compose.prod.yml with your container registry paths
   • Update .env.example with your default values
   • Update GitHub Actions workflows in .github/workflows/ with your registry
3. Start building your application!