WorkApp Deployment

Complete Docker-based deployment configuration for the WorkApp full-stack application.

🌐 Production Deployment

Live Application:

• Frontend: https://appointment-system-react-one.vercel.app
• Backend API: https://system-management-restapi.onrender.com
• Documentation: https://system-management-restapi.onrender.com/swagger-ui.html

Production Stack:

• Frontend deployed on Vercel with automatic HTTPS & CDN
• Backend deployed on Render using Docker containers
• Analytics: Vercel Analytics & Speed Insights enabled

⚠️ Note: This repository's Docker Compose setup is for local development. Production uses cloud platforms (Vercel + Render) for optimal performance and scalability.

📋 Table of Contents

• Overview
• System Architecture & Flow
• Prerequisites
• Quick Start
• Deployment Methods
• Environment Configuration
• Troubleshooting
• Security
• Related Repositories

Overview

This repository provides Docker Compose configuration for local development of the complete WorkApp system with:

• Backend API: Spring Boot REST API with JWT authentication
• Frontend: React TypeScript SPA with modern UI
• Database: MySQL 8.0 with automated initialization
• Auto-seeding: Pre-configured cities data
• Health checks: Automated container health monitoring

Production Deployment: For cloud deployment, see production URLs above. This Docker Compose setup is optimized for local development and testing.

System Architecture & Flow

graph LR
    User[User Browser<br/>:3000]
    Frontend[Frontend<br/>React + Nginx]
    Backend[Backend<br/>Spring Boot + JWT]
    DB[(MySQL 8.0<br/>:3307)]
    
    User -->|HTTP<br/>GET/POST| Frontend
    Frontend -->|REST API<br/>Bearer Token| Backend
    Backend -->|JDBC<br/>SELECT/INSERT| DB
    
    DB -.->|ResultSet| Backend
    Backend -.->|JSON| Frontend
    Frontend -.->|HTML/CSS| User
    
    style User fill:#f9f9f9,stroke:#333,color:#000
    style Frontend fill:#61DAFB,stroke:#333,color:#000
    style Backend fill:#6DB33F,stroke:#333,color:#fff
    style DB fill:#4479A1,stroke:#333,color:#fff
    
    linkStyle 0,1,2 stroke:#2ecc71,stroke-width:2px
    linkStyle 3,4,5 stroke:#e74c3c,stroke-width:2px

Loading

Flow:
🟢 Solid green arrows = Request
🔴 Dashed red arrows = Response

Components:

• Frontend: React 19, TypeScript, Vite, Tailwind CSS, Nginx
• Backend: Spring Boot 3.4.7, Java 17, JWT Authentication, Security Audit System
• Database: MySQL 8.0 with auto-initialization & seeding
• Network: Isolated Docker bridge network (workapp-network)

Prerequisites

• Docker Desktop (or Docker Engine + Docker Compose)
  • Windows/Mac: Docker Desktop
  • Linux: Docker Engine + Docker Compose plugin
• Ports available: 3000 (frontend), 8080 (backend), 3307 (database)
• Minimum: 4GB RAM, 2 CPU cores

Quick Start

Three commands to deploy:

git clone https://github.com/grgks/workapp-deployment.git
cd workapp-deployment
cp .env.example .env
# Edit .env with your passwords
docker-compose up -d

Access the application:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger-ui.html

Stop the application:

docker-compose down

Remove all data (including database):

docker-compose down -v

Deployment Methods

Method 1: Git Clone (Recommended)

# Clone repository
git clone https://github.com/grgks/workapp-deployment.git
cd workapp-deployment

# Configure environment
cp .env.example .env
nano .env  # Edit passwords

# Deploy
docker-compose up -d

# View logs
docker-compose logs -f

Method 2: Download ZIP (No Git Required)

1. Go to: https://github.com/grgks/workapp-deployment
2. Click Code → Download ZIP
3. Extract ZIP file
4. Open terminal in extracted folder
5. Copy .env.example to .env and edit
6. Run docker-compose up -d

Method 3: Manual Docker Pull

# Pull images manually
docker pull grgks/workapp-backend:latest
docker pull grgks/workapp-frontend:latest
docker pull mysql:8.0

# Then use docker-compose.yml from this repository

Environment Configuration

.env File Structure

# Database Configuration
DEPLOY_DB_NAME=appointment_system_restdb
DEPLOY_DB_USERNAME=app7sys
DEPLOY_DB_PASSWORD=your_secure_password_here
DEPLOY_JWT_SECRET=your_jwt_secret_minimum_256_bits

# Ports (Optional - defaults shown)
BACKEND_PORT=8080
FRONTEND_PORT=3000
DB_PORT=3307

# Docker Hub
DOCKER_USERNAME=grgks

JWT Secret Generation

⚠️ CRITICAL: The JWT secret MUST be Base64 encoded!

Using plain text or strings with special characters (like dashes) will cause authentication errors: "Illegal base64 character".

Generate a valid Base64-encoded JWT secret:

Linux/Mac/Git Bash:

echo -n "your-secret-phrase-minimum-256-bits-long" | base64

Windows PowerShell:

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("your-secret-phrase-minimum-256-bits-long"))

Online tool: https://www.base64encode.org/

Example:

# ❌ WRONG - Plain text with dashes (will cause errors)
DEPLOY_JWT_SECRET=my-super-secret-jwt-key-with-dashes

# ❌ WRONG - Special characters not Base64 encoded
DEPLOY_JWT_SECRET=MySecret@Key#2024!

# ✅ CORRECT - Base64 encoded string
DEPLOY_JWT_SECRET=bXktc3VwZXItc2VjcmV0LWp3dC1rZXktbWluaW11bS0yNTYtYml0cy1sb25nLWZvci1zZWN1cmUtZ2VuZXJhdGlvbg==

Why Base64? The JWT library expects the signing key in Base64 format for proper HMAC signature generation.

Required Variables

Variable	Description	Example	Required
DEPLOY_DB_NAME	MySQL database name	appointment_system_restdb	✅
DEPLOY_DB_USERNAME	MySQL application user	app7sys	✅
DEPLOY_DB_PASSWORD	MySQL password	mySecurePassword123	✅
DEPLOY_JWT_SECRET	JWT signing key (Base64 encoded)	bXktc3VwZXIuc2VjcmV0a2V5...	✅
MYSQL_ROOT_PASSWORD	MySQL root password	RootPass123!	✅

Optional Variables

Variable	Description	Default
BACKEND_PORT	Backend API port	8080
FRONTEND_PORT	Frontend port	3000
DB_PORT	MySQL port	3307

Security Notes:

• Use strong passwords (8+ characters)
• JWT secret must be 256 bits minimum
• Never commit .env to version control
• Change default passwords in production

Troubleshooting

Common Issues

Port Already in Use

Error: port is already allocated

Solution:

# Check what's using the port
netstat -ano | findstr :3306  # Windows
lsof -i :3306                 # Mac/Linux

# Option 1: Stop conflicting service
# Option 2: Change port in .env
DB_PORT=3307

Backend Keeps Restarting

Check logs:

docker logs workapp-backend --tail 50

Common causes:

1. Wrong database credentials
2. MySQL not ready (wait 30 seconds)
3. Missing JWT_SECRET

Solution: Verify .env variables match MySQL configuration

Database Connection Failed

Check MySQL is healthy:

docker ps
# workapp-db should show "healthy"

Test connection:

docker exec -it workapp-db mysql -u app7sys -p[PASSWORD] -e "SHOW DATABASES;"

Frontend Shows "Network Error"

Verify backend is running:

curl http://localhost:8080/actuator/health

Check backend logs:

docker logs workapp-backend

Clean Restart

If things go wrong, perform a clean restart:

# Stop and remove everything
docker-compose down -v

# Remove old images (optional)
docker rmi grgks/workapp-backend:latest
docker rmi grgks/workapp-frontend:latest

# Fresh start
docker-compose up -d

Security

Automated Security Scanning

All images are automatically scanned for vulnerabilities:

• Docker Scout: Base image scanning
• Trivy: Comprehensive CVE detection
• GitHub Security: Continuous monitoring

View security reports:

• Backend Security
• Frontend Security

Production Recommendations

• Change all default passwords
• Use environment-specific .env files
• Enable HTTPS (reverse proxy)
• Implement rate limiting
• Regular security updates
• Monitor logs for suspicious activity
• Backup database regularly

Related Repositories

Application Code

• Backend API: system-management-restAPI

  • Spring Boot 3.x, Java 17
  • JWT Authentication & Security Audit System
  • RESTful API with Swagger
  • 193 tests, 78% coverage
  • Real-time security monitoring & event tracking

• Frontend: appointment-system-react

  • React 19, TypeScript
  • Modern UI with Tailwind CSS
  • Vite build system

Docker Images

• Backend: grgks/workapp-backend

  • Multi-stage build
  • Optimized: 384MB → 123MB compressed
  • Health checks included

• Frontend: grgks/workapp-frontend

  • Nginx-based
  • Size: 84MB
  • Production-optimized

🚀 Production vs Development

Local Development (This Repository)

• Purpose: Development, testing, and demonstration
• Stack: Docker Compose with MySQL
• URLs: localhost:3000 (frontend), localhost:8080 (backend)
• Database: Local MySQL container
• Best for: Development, learning, local testing

Production Deployment

• Purpose: Live application for end users
• Frontend: Vercel (https://appointment-system-react-one.vercel.app)
  • Automatic deployments from GitHub
  • Global CDN for fast loading
  • Analytics & Speed Insights enabled
• Backend: Render (https://system-management-restapi.onrender.com)
  • Docker-based deployment
  • Automatic HTTPS
  • Environment variables management
• Database: MySQL 8.0 (managed service)
• Best for: Production use, public access

Note: The production deployment uses the same Docker images from this repository, ensuring consistency between development and production environments.

---

📄 License

MIT License

👤 Author

grgks

• GitHub: @grgks
• Docker Hub: grgks

---

Need help? Open an issue in the deployment repository