FreeLang Starter Kit v2.0

Production-ready web application template for FreeLang 2.0

배포 자동화 시스템의 health check 테스트용 프로덕션급 웹 서버

⚡ Quick Start

1. Clone Repository

cd /home/kimjin/Desktop/kim
git clone https://gogs.dclub.kr/kim/freelang-starter-kit.git
cd freelang-starter-kit

2. Install Dependencies

npm install

3. Start Server

# Default port 3000
npm start

# Custom port
PORT=8080 npm start

# Production port
PORT=40010 npm start

4. Health Check

# In another terminal
curl http://localhost:3000/health

# Response:
# {
#   "status": "healthy",
#   "version": "2.0.0",
#   "environment": "development",
#   "uptime": 2.345,
#   "requests": 5,
#   "timestamp": "2025-02-01T10:30:45Z"
# }

✨ Features

Core Functionality

• ✅ HTTP Server - Express-like routing with FreeLang
• ✅ Health Check - /health endpoint for deployment automation
• ✅ CRUD API - User management example with JSON responses
• ✅ Environment Variables - PORT, HOST, NODE_ENV support
• ✅ Middleware Stack - Logger, CORS, Error handling
• ✅ Logging - Request/response logging with timestamps

Production Ready

• ✅ PM2 Configuration - Process management setup
• ✅ Nginx Configuration - Reverse proxy with caching
• ✅ Docker Support - Containerization ready
• ✅ Error Handling - Graceful error responses
• ✅ Security Headers - CORS, XSS protection, etc.

Developer Experience

• ✅ Simple Structure - Easy to understand and extend
• ✅ Code Comments - Well-documented source
• ✅ npm Scripts - Common tasks automated
• ✅ Example APIs - CRUD operations example
• ✅ Documentation - API docs and deployment guides

📋 API Endpoints

System

| Method | Path | Description | Response | |--------|------|-------------|----------| | GET | / | API info | {name, version, endpoints} | | GET | /health | Health check (배포용) | {status, version, uptime, ...} |

Users

| Method | Path | Description | Status | |--------|------|-------------|--------| | GET | /api/users | List all users | 200 OK | | GET | /api/users/:id | Get user by ID | 200 OK / 404 Not Found | | POST | /api/users | Create new user | 201 Created / 400 Bad Request | | PUT | /api/users/:id | Update user | 200 OK / 404 Not Found | | DELETE | /api/users/:id | Delete user | 200 OK / 404 Not Found |

Example: Create User

curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice",
    "email": "[email protected]"
  }'

# Response:
# {
#   "success": true,
#   "data": {
#     "id": "user_123456",
#     "name": "Alice",
#     "email": "[email protected]",
#     "active": true,
#     "createdAt": "2025-02-01T10:30:45Z"
#   }
# }

🔧 Configuration

Environment Variables

Create .env file from .env.example:

cp .env.example .env

Available variables:

PORT=3000              # Server port (default: 3000)
HOST=0.0.0.0          # Server host (default: 0.0.0.0)
NODE_ENV=development  # Environment: development|production
LOG_LEVEL=info        # Logging level: debug|info|warn|error

npm Scripts

npm start              # Start server (PORT from env or 3000)
npm run dev           # Start in development (port 3000)
npm run build         # Compile FreeLang code
npm run test          # Run tests
npm run deploy        # Deploy to production

# PM2
npm run pm2:start     # Start with PM2
npm run pm2:stop      # Stop PM2 service
npm run pm2:restart   # Restart PM2 service
npm run pm2:logs      # View PM2 logs

# Utils
npm run health        # Check health endpoint

🚀 Deployment

Development (Local)

cd /home/kimjin/Desktop/kim/freelang-starter-kit
PORT=3000 npm start

Production (PM2)

# Start
npm run pm2:start

# Logs
npm run pm2:logs

# Restart
npm run pm2:restart

# Stop
npm run pm2:stop

Port Manager (Automated)

# System automatically assigns port
curl -X POST http://localhost:45000/api/servers/start \
  -H "Content-Type: application/json" \
  -d '{
    "name": "freelang-starter",
    "command": "cd /home/kimjin/Desktop/kim/freelang-starter-kit && PORT={port} npm start"
  }'

# Response:
# {
#   "success": true,
#   "server_id": 1,
#   "port": 40010,
#   "name": "freelang-starter",
#   "pid": 12345
# }

Docker

# Build image
docker build -t freelang-starter:2.0.0 .

# Run container
docker run -p 3000:3000 \
  -e PORT=3000 \
  -e NODE_ENV=production \
  freelang-starter:2.0.0

# Docker Compose
docker-compose up -d

Nginx Reverse Proxy

# Copy configuration
sudo cp deployment/nginx.conf /etc/nginx/sites-available/freelang-starter

# Enable
sudo ln -s /etc/nginx/sites-available/freelang-starter /etc/nginx/sites-enabled/

# Test
sudo nginx -t

# Reload
sudo systemctl reload nginx

# Access via Nginx
curl http://localhost/health

📊 Project Structure

freelang-starter-kit/
├── README.md                          # This file
├── package.json                       # npm configuration
├── .env.example                       # Environment variables template
├── .gitignore                         # Git ignore rules
│
├── src/
│   ├── main.free                      # ⭐ Main server (300 lines)
│   ├── routes/                        # Route handlers (future)
│   ├── middleware/                    # Middleware (future)
│   ├── services/                      # Business logic (future)
│   └── utils/                         # Utilities (future)
│
├── deployment/
│   ├── ecosystem.config.js            # PM2 configuration
│   ├── nginx.conf                     # Nginx reverse proxy
│   └── docker/
│       ├── Dockerfile
│       └── docker-compose.yml
│
├── scripts/
│   ├── deploy.sh                      # Deployment script
│   ├── test.sh                        # Test runner
│   └── build.sh                       # Build script
│
├── tests/
│   ├── health.test.free               # Health check tests
│   └── users.test.free                # User API tests
│
├── docs/
│   ├── API.md                         # API documentation
│   ├── DEPLOYMENT.md                  # Deployment guide
│   └── ARCHITECTURE.md                # Architecture overview
│
└── logs/
    └── (created at runtime)

🧪 Testing

Health Check Test

# Start server
PORT=3000 npm start &

# In another terminal
sleep 2
curl -s http://localhost:3000/health | jq .

# Expected output:
# {
#   "status": "healthy",
#   "version": "2.0.0",
#   ...
# }

User API Test

# List users
curl http://localhost:3000/api/users

# Create user
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Bob","email":"[email protected]"}'

# Get user
curl http://localhost:3000/api/users/user_123456

# Update user
curl -X PUT http://localhost:3000/api/users/user_123456 \
  -H "Content-Type: application/json" \
  -d '{"name":"Robert"}'

# Delete user
curl -X DELETE http://localhost:3000/api/users/user_123456

🔍 Deployment Automation Integration

This starter kit is designed for testing FreeLang deployment automation:

Health Check (배포 자동화 검증)

The /health endpoint returns deployment-critical information:

{
  "status": "healthy",
  "version": "2.0.0",
  "environment": "production",
  "uptime": 123.456,
  "requests": 45,
  "timestamp": "2025-02-01T10:30:45Z",
  "host": "0.0.0.0",
  "port": "40010"
}

Deployment Script Integration

# In /home/kimjin/Desktop/kim/freelang/scripts/deploy-canary.sh

# 1. Start server
PORT=40010 npm start &

# 2. Wait for startup
sleep 5

# 3. Health check
curl http://localhost:40010/health

# 4. Verify response
# If "status": "healthy" → deployment success
# Otherwise → deployment failed

📚 Documentation

• API Documentation - Complete API reference
• Deployment Guide - Production deployment guide
• Architecture - System architecture overview

🛠️ Technology Stack

• Language: FreeLang 2.0
• Runtime: Node.js (FreeLang compiled to JS)
• Process Manager: PM2
• Reverse Proxy: Nginx
• Containerization: Docker
• Package Manager: npm / KPM
• Platform: Linux (192.168.45.73, 192.168.45.253)

🔐 Security

Built-in Security Features

• ✅ CORS headers (configurable)
• ✅ XSS protection
• ✅ Input validation
• ✅ Error message sanitization
• ✅ Security headers (Nginx)
• ✅ Rate limiting ready (via Nginx)

Production Checklist

• [ ] Update ALLOWED_ORIGINS in .env
• [ ] Enable HTTPS in Nginx
• [ ] Configure rate limiting
• [ ] Set up monitoring/logging
• [ ] Enable access logs
• [ ] Regular security updates

🐛 Troubleshooting

Port Already in Use

# Find process using port
lsof -i :3000

# Kill process
kill -9 <PID>

# Or use different port
PORT=3001 npm start

Health Check Fails

# Check server is running
ps aux | grep freelang

# Check logs
npm run pm2:logs

# Test connectivity
curl -v http://localhost:3000/health

FreeLang Not Found

# Install FreeLang
npm install -g freelang

# Verify installation
freelang --version

# Check npm path
which freelang

📝 Version History

v2.0.0 (2025-02-01)

• ✨ Complete production-ready implementation
• ✨ Health check endpoint for deployment automation
• ✨ Full CRUD API example
• ✨ PM2, Nginx, Docker configurations
• ✨ Comprehensive documentation

v1.0.0 (2025-01-15)

• Initial release
• Basic HTTP server
• Routes example

📖 FreeLang Resources

• GitHub: https://github.com/freelang-lang/freelang
• Docs: https://freelang.org/docs
• Examples: https://github.com/freelang-lang/examples
• Community: https://discord.gg/freelang

🤝 Contributing

To extend this starter kit:

1. Create a new branch
2. Make your changes in src/
3. Test with npm start
4. Update documentation
5. Submit pull request

📄 License

MIT License - See LICENSE file for details

👨‍💻 Author

kim - FreeLang Starter Kit Creator

• Repository: https://gogs.dclub.kr/kim/freelang-starter-kit
• Contact: [email protected]

🎯 Next Steps

Extend the Starter Kit

1. Modularize - Split main.free into separate route files
2. Database - Add PostgreSQL integration
3. Authentication - Implement JWT auth
4. Validation - Add input validation middleware
5. Testing - Write comprehensive test suite
6. Monitoring - Add metrics and observability

Use as Template

# Clone for new project
git clone https://gogs.dclub.kr/kim/freelang-starter-kit.git my-new-app
cd my-new-app
git remote set-url origin https://gogs.dclub.kr/kim/my-new-app.git
# Start developing!

🧪 Testing (Jest)

Run Tests

# Run all tests with coverage
npm run test

# Run tests in watch mode
npm run test:watch

# Run only legacy bash tests
npm run test:legacy

Test Coverage

Tests: 16+ test cases
Coverage: 60%+
Categories:
  - Server creation
  - Root endpoint
  - Health check
  - User CRUD operations
  - Error handling
  - CORS headers
  - Request tracking

📦 npm Package

This starter kit is registered on npm as freelang-starter-kit.

Install from npm

npm install freelang-starter-kit
# or
npm install -g freelang-starter-kit

Use as Template

npx freelang-starter-kit

Last Updated: 2025-02-17 Status: Production Ready ✅ (v2.0.0+)