Skip to content

README.md

Latest commit

 

History

History
306 lines (235 loc) · 8.78 KB

README.md

File metadata and controls

306 lines (235 loc) · 8.78 KB

AdonisJS v6 React Starter Kit with Docker

This project provides a complete Docker setup for running an AdonisJS v6 React starter kit application with SurrealDB and Nginx.

Project Structure

.
├── backend/                 # AdonisJS v6 React starter kit application
│   ├── app/                # Application code
│   ├── config/             # Configuration files
│   ├── resources/          # Frontend resources
│   ├── package.json        # Node.js dependencies
│   └── ...
├── infra/                  # Infrastructure configuration
│   ├── container/          # Docker configuration
│   │   ├── Dockerfile      # Production Docker image
│   │   ├── Dockerfile.dev  # Development Docker image
│   │   ├── docker-compose.yml      # Production services
│   │   ├── docker-compose.dev.yml  # Development services
│   │   ├── docker-scripts.sh       # Management script
│   │   ├── .dockerignore           # Docker build exclusions
│   │   └── nginx/          # Nginx configuration
│   │       ├── nginx.conf         # Main Nginx configuration
│   │       └── conf.d/
│   │           └── default.conf   # Server configuration with wildcard support
│   └── kubernetes/         # Kubernetes configuration (future)
└── README.md              # This file

Architecture

  • Web: AdonisJS v6 React starter kit application
  • Database: SurrealDB (NoSQL database)
  • Reverse Proxy: Nginx for load balancing, SSL termination, and wildcard subdomain support

Prerequisites

  • Docker
  • Docker Compose
  • Node.js 18+ (for local development)

Quick Start

Production

  1. Navigate to the container directory:
cd infra/container
  1. Build and start all services:
./docker-scripts.sh prod
# or
docker-compose up --build
  1. Access your application:

Development

  1. Navigate to the container directory:
cd infra/container
  1. Start development environment with hot reloading:
./docker-scripts.sh dev
# or
docker-compose -f docker-compose.dev.yml up --build
  1. Access your application:

Wildcard Subdomain Support

IMPORTANT: This setup includes wildcard subdomain support! All subdomains will point to your AdonisJS v6 app's welcome page.

How it works:

  • Any subdomain (e.g., api.example.com, admin.example.com, test.example.com) will be handled by Nginx
  • All requests are proxied to the AdonisJS v6 application
  • The application receives the original hostname in the Host header
  • You can access your app via any subdomain you configure in your DNS

Examples:

  • localhost → AdonisJS app
  • api.localhost → AdonisJS app
  • admin.localhost → AdonisJS app
  • test.localhost → AdonisJS app
  • anything.localhost → AdonisJS app

Configuration:

  • Nginx uses a wildcard server block with server_name ~^.*$;
  • All subdomains are automatically handled
  • The original hostname is preserved in headers for your application logic

Services

Web Application (AdonisJS v6)

  • Port: 3333 (internal), 3333 (external)
  • Environment: Production/Development
  • Features: React frontend with AdonisJS backend
  • Subdomain Support: All subdomains point to this application
  • Location: backend/ directory

SurrealDB

  • Port: 8000
  • Credentials: root/root
  • Storage: Persistent volume
  • Mode: Memory (for development)

Nginx

  • Port: 80 (HTTP), 443 (HTTPS - commented out)
  • Features: Reverse proxy, load balancing, SSL termination, wildcard subdomain support
  • Static files: Served from /app/public/
  • Subdomain Handling: All subdomains are automatically routed to the AdonisJS app
  • Location: infra/container/nginx/ directory

Configuration

Environment Variables

The following environment variables are available:

  • NODE_ENV: Environment (production/development)
  • PORT: Application port (default: 3333)
  • DATABASE_URL: SurrealDB connection string

Nginx Configuration

  • Main config: infra/container/nginx/nginx.conf
  • Server config: infra/container/nginx/conf.d/default.conf (includes wildcard support)
  • SSL certificates: infra/container/ssl/ directory (create your own)

SurrealDB Configuration

  • Username: root
  • Password: root
  • Database: In-memory (development) or file-based (production)

Development Workflow

  1. Navigate to container directory:

    cd infra/container

  2. Start development environment:

    ./docker-scripts.sh dev

  3. Make changes to your code in the backend/ directory - they will be automatically reflected due to volume mounting

  4. Test subdomains - access your app via any subdomain (e.g., api.localhost:8080)

  5. View logs:

    ./docker-scripts.sh logs web

  6. Stop services:

    ./docker-scripts.sh stop

Production Deployment

  1. Navigate to container directory:

    cd infra/container

  2. Build and start production services:

    ./docker-scripts.sh prod

  3. Set up SSL certificates:

    • Place your SSL certificates in the ssl/ directory
    • Uncomment HTTPS configuration in nginx/conf.d/default.conf
    • Consider using wildcard SSL certificates for subdomain support

  4. Configure environment variables:

    • Create a .env file in the backend/ directory with production values
    • Update docker-compose.yml with proper environment variables

  5. DNS Configuration:

    • Point your domain to your server
    • Configure wildcard DNS record (*.yourdomain.com) to point to your server
    • All subdomains will automatically work

Useful Commands

All commands should be run from the infra/container/ directory:

# Navigate to container directory
cd infra/container

# Use the management script
./docker-scripts.sh dev          # Start development
./docker-scripts.sh prod         # Start production
./docker-scripts.sh stop         # Stop all services
./docker-scripts.sh logs web     # View web logs
./docker-scripts.sh status       # Show service status
./docker-scripts.sh cleanup      # Clean up everything

# Or use docker-compose directly
docker-compose up --build        # Production
docker-compose -f docker-compose.dev.yml up --build  # Development
docker-compose down              # Stop services
docker-compose logs -f web       # View logs
docker-compose exec web npm test # Run tests

Local Development with Custom Domain

To use myapp.test locally:

  1. Edit your /etc/hosts file:

    sudo nano /etc/hosts

    Add:

    127.0.0.1 myapp.test *.myapp.test

  2. Start the development environment:

    cd infra/container
./docker-scripts.sh dev

  3. Access your app:

Troubleshooting

Common Issues

  1. Port conflicts: Ensure ports 80, 3333, and 8000 are available
  2. Permission issues: Run Docker commands with appropriate permissions
  3. Build failures: Check if all dependencies are properly specified in backend/package.json
  4. Subdomain not working: Check DNS configuration and ensure wildcard records are set up
  5. Wrong directory: Make sure you're running commands from infra/container/

Logs

View logs for specific services:

cd infra/container
./docker-scripts.sh logs web
./docker-scripts.sh logs surrealdb
./docker-scripts.sh logs nginx

Database Connection

To connect to SurrealDB directly:

cd infra/container
docker-compose exec surrealdb surreal sql --conn http://localhost:8000 --user root --pass root

Testing Subdomains

Test wildcard subdomain functionality:

# Test different subdomains
curl -H "Host: api.localhost" http://localhost:8080
curl -H "Host: admin.localhost" http://localhost:8080
curl -H "Host: test.localhost" http://localhost:8080

Security Notes

  • Change default SurrealDB credentials in production
  • Set up proper SSL certificates (consider wildcard certificates for subdomains)
  • Configure firewall rules
  • Use environment variables for sensitive data
  • Regularly update Docker images
  • Consider rate limiting for subdomains if needed

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes in the appropriate directories (backend/ for app code, infra/container/ for Docker config)
  4. Test with Docker and subdomains
  5. Submit a pull request

License

This project is licensed under the MIT License.