Skip to content

README.md

Latest commit

 

History

History
224 lines (147 loc) · 5.83 KB

README.md

File metadata and controls

224 lines (147 loc) · 5.83 KB

Local HTTPS Development Setup

This folder contains all the scripts and configuration files needed to run the Marine Licensing Frontend application locally with HTTPS support and on how to point local to cp dev defra id instance instead of stub.

🚀 Quick Start

Prerequisites

  1. Install mkcert (for local SSL certificates):

    brew install mkcert
mkcert -install

    Or with macports

    sudo port install mkcert

  2. Install nginx (if not already installed):

    brew install nginx

    Or with macports:

    sudo port install nginx
#  Do not configure to run at startup

  3. Set up nginx directories (required for Homebrew nginx):

    sudo mkdir -p /usr/local/var/run/nginx
sudo chown -R $(whoami):admin /usr/local/var/run/nginx

    ⚠️ Important: This step is required to set the working directory correctly for Homebrew installed nginx.

    For Macports: the default config file is /opt/local/etc/nginx/nginx.conf

  4. Generate SSL certificates (first time only):

    cd local-https-setup
mkcert marine-licensing-frontend.test.cdp-int.defra.cloud
cd ..

    ⚠️ Important: SSL certificates are generated locally and should NOT be committed to the repository. The certificates are already in .gitignore to prevent accidental commits.

  5. Enable local DNS (first time only):

    ./local-https-setup/toggle-local-dns.sh

  6. Rename the .env.template file in the frontend repo root, to .env (it will be git-ignored) and obtain the missing secret values from another team member. Compare other values with here https://github.com/DEFRA/cdp-app-config/blob/main/services/marine-licensing-frontend/test/marine-licensing-frontend.env

  7. Rename the .env.template in the backend repo root as .env and check the values are the same as https://github.com/DEFRA/cdp-app-config/blob/main/services/marine-licensing-backend/test/marine-licensing-backend.env

Start the Application

./local-https-setup/start-with-https.sh

📁 Files Overview

Configuration Files

  • nginx-https.conf - Nginx configuration for HTTP and HTTPS reverse proxy
  • README.md - This documentation file

Startup Scripts

  • start-with-https.sh - Starts application with HTTPS support
  • toggle-local-dns.sh - Toggle between local and remote DNS resolution
  • stop-all.sh - Stop all running processes and clean up

🔧 How It Works

Architecture

Browser → HTTPS (443) → Nginx → HTTP (3000) → Node.js App
Browser → HTTP (80)  → Nginx → HTTP (3000) → Node.js App

Components

  1. Nginx Reverse Proxy: Handles SSL termination and forwards requests to localhost:3000
  2. SSL Certificates: Generated by mkcert for local development
  3. DNS Resolution: Local /etc/hosts entry for domain mapping
  4. Environment Variables: Configured for OIDC and base URL

🌐 Access URLs

Once started, access your application at:

  • HTTP: http://marine-licensing-frontend.test.cdp-int.defra.cloud
  • HTTPS: https://marine-licensing-frontend.test.cdp-int.defra.cloud

🔄 DNS Management

Enable Local Development

./local-https-setup/toggle-local-dns.sh

This will:

  • Add 127.0.0.1 marine-licensing-frontend.test.cdp-int.defra.cloud to /etc/hosts
  • Flush DNS cache
  • Domain will resolve to localhost

Disable Local Development (Use Remote)

./local-https-setup/toggle-local-dns.sh

This will:

  • Comment out the local DNS entry
  • Flush DNS cache
  • Domain will resolve to remote test environment

🛑 Stopping the Application

Graceful Stop

Press Ctrl+C in the terminal where the startup script is running.

Force Stop All Processes

./local-https-setup/stop-all.sh

🔍 Troubleshooting

SSL Certificate Issues

If you see SSL errors:

  1. Ensure mkcert is installed: brew install mkcert
  2. Install mkcert root CA: mkcert -install
  3. Generate new certificates: 
    cd local-https-setup
rm -f *.pem  # Remove existing certificates
mkcert marine-licensing-frontend.test.cdp-int.defra.cloud
cd ..

    Note: Each developer should generate their own SSL certificates locally. Never commit certificate files to the repository.

Port Conflicts

If ports are already in use:

./local-https-setup/stop-all.sh

DNS Issues

If domain doesn't resolve:

  1. Check /etc/hosts entry: grep marine-licensing-frontend.test.cdp-int.defra.cloud /etc/hosts
  2. Flush DNS cache: sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
  3. Use toggle script: ./local-https-setup/toggle-local-dns.sh

🔧 Environment Variables

The scripts automatically set these environment variables:

  • APP_BASE_URL: https://marine-licensing-frontend.test.cdp-int.defra.cloud

📝 Manual Commands

If you prefer to run commands manually:

Start Nginx Only

sudo nginx -c $(pwd)/local-https-setup/nginx-https.conf

Start Application Only

export APP_BASE_URL=https://marine-licensing-frontend.test.cdp-int.defra.cloud
npm run dev

Stop Nginx

sudo nginx -s stop

🔒 Security Notes

  • SSL certificates are for local development only
  • Never use these certificates in production
  • The setup uses self-signed certificates generated by mkcert
  • Browser may show security warnings - this is normal for local development
  • SSL certificates are NOT committed to the repository - each developer generates their own locally
  • Certificate files (*.pem) are excluded via .gitignore to prevent accidental commits

📞 Support

If you encounter issues:

  1. Check the troubleshooting section above
  2. Verify all prerequisites are installed
  3. Ensure no other services are using ports 80, 443, or 3000
  4. Check application logs for specific error messages