Full-Stack Application

A modern full-stack application with React frontend, Go backend, and PostgreSQL database, designed for scalable deployment with Docker and comprehensive CI/CD pipeline.

Architecture

• Frontend: React + Vite + TypeScript + Tailwind CSS + Vitest + Nginx
• Backend: Go + Gin + Clean Architecture + PostgreSQL + GORM
• Shared: OpenAPI specs + TypeScript types
• Infrastructure: Docker + docker-compose + Kubernetes + GitHub Actions
• Deployment: Automated CI/CD with testing, building, and deployment

Project Structure

├── frontend/              # React frontend application
│   ├── Dockerfile        # Production Dockerfile (Nginx)
│   ├── Dockerfile.dev    # Development Dockerfile
│   └── nginx.conf        # Nginx configuration
├── backend/              # Go backend application
│   └── Dockerfile        # Production Dockerfile
├── shared/               # Shared OpenAPI specs and types
├── infrastructure/       # Kubernetes deployment configs
├── scripts/              # Deployment and maintenance scripts
│   ├── deploy.sh         # Production deployment script
│   ├── setup-server.sh   # Server setup script
│   └── backup.sh         # Backup and restore script
├── .github/workflows/    # GitHub Actions CI/CD
├── docker-compose.yml    # Local development setup
├── docker-compose.prod.yml # Production setup
└── README.md

Quick Start

Development Setup

1. Prerequisites: Docker, Docker Compose, Node.js 18+, Go 1.21+
2. Clone repository: git clone <your-repo-url>
3. Start services: docker-compose up -d
4. Frontend development: cd frontend && npm run dev
5. Backend development: cd backend && go run main.go

Development Services

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080
• PostgreSQL: localhost:5432

Production Deployment

Prerequisites

• Linux server (Ubuntu 20.04+ or CentOS 8+ recommended)
• Domain name (optional, for SSL)
• SSH access to server

Step 1: Server Setup

Run the server setup script on your Linux server:

# Download and run server setup script
curl -sSL https://raw.githubusercontent.com/yourusername/your-repo/main/scripts/setup-server.sh | sudo bash

Or manually:

# Copy script to server
scp scripts/setup-server.sh user@your-server:/tmp/
ssh user@your-server
sudo chmod +x /tmp/setup-server.sh
sudo /tmp/setup-server.sh

This script will:

• Install Docker and Docker Compose
• Setup firewall (ports 80, 443, 22)
• Create application user and directories
• Configure SSL certificates (optional)
• Install monitoring tools
• Optimize system for Docker

Step 2: Application Deployment

Option A: Automated Deployment with GitHub Actions

1. Configure GitHub Secrets:

   • DEPLOY_HOST: Your server IP or domain
   • DEPLOY_USER: SSH username (typically 'appuser')
   • DEPLOY_KEY: SSH private key for server access

2. Configure Environment Variables: Create .env.production on your server:

   ssh appuser@your-server
   cd /opt/fullstack-app
   cat > .env.production << EOF
   POSTGRES_DB=appdb
   POSTGRES_USER=user
   POSTGRES_PASSWORD=your-secure-password
   GIN_MODE=release
   PORT=8080
   EOF

3. Deploy: Push to main branch triggers automatic deployment

Option B: Manual Deployment

1. Clone repository on server:

   ssh appuser@your-server
   cd /opt/fullstack-app
   git clone https://github.com/yourusername/your-repo.git .

2. Configure environment:

   cp .env.example .env.production
   # Edit .env.production with your settings

3. Deploy:

   chmod +x scripts/deploy.sh
   ./scripts/deploy.sh

Step 3: Configure Reverse Proxy (Optional)

For custom domain and SSL:

# Install Nginx
sudo apt install nginx

# Configure Nginx
sudo tee /etc/nginx/sites-available/your-app << EOF
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;
    }
}
EOF

# Enable site
sudo ln -s /etc/nginx/sites-available/your-app /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Setup SSL with Let's Encrypt
sudo certbot --nginx -d your-domain.com

CI/CD Pipeline

The GitHub Actions workflow automatically:

1. Tests: Runs frontend and backend tests
2. Builds: Creates Docker images
3. Pushes: Uploads images to GitHub Container Registry
4. Deploys: Deploys to production server on main branch

Pipeline Triggers

• Pull Requests: Runs tests only
• Push to main: Full pipeline with deployment
• Push to develop: Tests and builds (no deployment)

Monitoring and Maintenance

Health Checks

# Check application status
./scripts/deploy.sh status

# Check individual services
docker-compose -f docker-compose.prod.yml ps
docker-compose -f docker-compose.prod.yml logs

Backups

# Create backup
./scripts/backup.sh

# List backups
./scripts/backup.sh list

# Restore from backup
./scripts/backup.sh restore 20231215_143022

System Monitoring

# System resources
htop
df -h
docker stats

# Application logs
docker-compose -f docker-compose.prod.yml logs -f

Environment Variables

Frontend (.env files)

VITE_API_URL=http://localhost:8080  # Development
VITE_API_URL=/api                   # Production (proxied)

Backend (.env.production)

# Database
POSTGRES_DB=appdb
POSTGRES_USER=user
POSTGRES_PASSWORD=your-secure-password
DATABASE_URL=postgres://user:password@postgres:5432/appdb?sslmode=disable

# Application
GIN_MODE=release
PORT=8080

# Optional: External services
REDIS_URL=redis://localhost:6379
SMTP_HOST=smtp.example.com
SMTP_PORT=587

Development

Frontend Commands

cd frontend
npm run dev          # Start development server
npm run build        # Build for production
npm run lint         # Run ESLint
npm run test         # Run tests
npm run test:coverage # Run tests with coverage

Backend Commands

cd backend
go run main.go       # Start development server
go build            # Build binary
go test ./...        # Run tests
go test -race ./...  # Run tests with race detection

Docker Commands

# Development
docker-compose up -d              # Start all services
docker-compose down               # Stop all services
docker-compose logs -f [service]  # View logs

# Production
docker-compose -f docker-compose.prod.yml up -d
docker-compose -f docker-compose.prod.yml down

Troubleshooting

Common Issues

1. Port conflicts: Change ports in docker-compose.yml
2. Database connection: Check DATABASE_URL and container networking
3. Build failures: Ensure all dependencies are installed
4. SSL issues: Verify domain DNS and firewall settings

Debug Commands

# Check Docker
docker ps
docker logs <container-name>
docker exec -it <container-name> /bin/sh

# Check network
docker network ls
docker network inspect <network-name>

# Check volumes
docker volume ls
docker volume inspect <volume-name>

Performance Optimization

1. Frontend: Enable gzip in Nginx, optimize bundle size
2. Backend: Connection pooling, caching, profiling
3. Database: Indexes, query optimization, connection limits
4. Infrastructure: Load balancing, CDN, monitoring

Security

• Environment variables for sensitive data
• Docker non-root users
• Firewall configuration
• SSL/TLS encryption
• Regular security updates
• Database access restrictions

Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.