Initial Setup - Admin Panel
This guide provides comprehensive instructions for setting up the Admin Panel service for the first time, including server configuration, Nginx reverse proxy setup, and environment configuration.
Prerequisites
Before beginning the setup process, ensure you have:
- Virtual Machine: 1 VM with a public IP address
- Security Group Configuration: Ports 22 (SSH), 80 (HTTP), and 443 (HTTPS) must be open
- SSL Certificates: Valid SSL certificate files (certificate.crt and private.key)
- Domain Name: Domain name configured to point to the VM's public IP
- GitHub Repository Access: Access to configure secret environments
- Docker Knowledge: Basic understanding of Docker and Docker Compose
Step 1: Server Preparation
1.1 Connect to the Server
SSH into your virtual machine using your credentials:
ssh user@your-server-ip
1.2 Install Docker Engine
Install Docker Engine on Ubuntu by following the official Docker documentation:
# Visit and follow instructions from:
# https://docs.docker.com/engine/install/ubuntu/
For Ubuntu, you can use the convenience script:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
After adding your user to the docker group, log out and log back in for the changes to take effect.
1.3 Verify Docker Installation
Verify that Docker is installed correctly:
docker --version
docker compose version
Step 2: Nginx Reverse Proxy Setup
The Admin Panel will be served through an Nginx reverse proxy container to handle SSL termination and routing.
2.1 Create Nginx Directory Structure
Create the necessary directory structure for Nginx configuration:
mkdir -p nginx/certs
cd nginx
2.2 Add SSL Certificates
Place your SSL certificate files in the certs directory:
# Copy your SSL certificate files
cp /path/to/your/certificate.crt ./certs/certificate.crt
cp /path/to/your/private.key ./certs/private.key
# Set appropriate permissions
chmod 644 ./certs/certificate.crt
chmod 600 ./certs/private.key
Ensure that private key files have restricted permissions (600) to prevent unauthorized access.
2.3 Create Docker Compose File
Create a docker-compose.yaml or compose.yaml file with the following configuration:
services:
nginx:
image: nginx:1.25-alpine
container_name: nginx-admin-panel
restart: always
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
- ./certs/certificate.crt:/etc/nginx/certs/certificate.crt:ro
- ./certs/private.key:/etc/nginx/certs/private.key:ro
networks:
- sbmcrm-network
depends_on:
- admin-panel
healthcheck:
test: ["CMD", "nginx", "-t"]
interval: 30s
timeout: 10s
retries: 3
networks:
sbmcrm-network:
external: true
The sbmcrm-network must be created before starting the containers. Create it with:
docker network create sbmcrm-network
2.4 Create Nginx Configuration
Create an nginx.conf file with the following configuration:
# Upstream configuration for Admin Panel service
upstream admin-panel {
server admin-panel-container:3000;
}
# HTTP (Port 80) Server Block - Redirect to HTTPS
server {
listen 80;
listen [::]:80;
server_name admin.example.com;
server_tokens off;
# Redirect all HTTP traffic to HTTPS
return 301 https://$host$request_uri;
}
# HTTPS (Port 443) Server Block
server {
listen 443 ssl http2;
listen [::]:443 ssl http2;
server_name admin.example.com;
# Client upload size limit
client_max_body_size 500m;
# SSL Certificate Configuration
ssl_certificate /etc/nginx/certs/certificate.crt;
ssl_certificate_key /etc/nginx/certs/private.key;
# Recommended TLS Settings
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES256-GCM-SHA384';
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1h;
ssl_session_tickets off;
# Security Headers
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
# Main Location Block
location / {
resolver 127.0.0.11 valid=30s;
# Proxy to the Admin Panel upstream
proxy_pass http://admin-panel;
# HTTP Version and WebSocket Support
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $http_host;
# Forward Client Information
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 https;
# Cookie Forwarding
proxy_pass_header Set-Cookie;
# Timeout Settings
proxy_read_timeout 300s;
proxy_connect_timeout 300s;
proxy_send_timeout 300s;
send_timeout 300s;
# Cache Bypass for WebSocket
proxy_cache_bypass $http_upgrade;
}
}
Replace the following placeholders in the configuration:
admin.example.com: Your actual domain nameadmin-panel-container: The Docker container name for the Admin Panel service3000: The internal port the Admin Panel service listens on (adjust if different)
2.5 Start Nginx Container
Start the Nginx reverse proxy:
docker compose up -d
Verify that the container is running:
docker ps
docker logs nginx-admin-panel
2.6 Test Nginx Configuration
Test the Nginx configuration for syntax errors:
docker exec nginx-admin-panel nginx -t
Step 3: Configure Secret Environments
Configure the required secret environment variables in your GitHub repository.
3.1 Access GitHub Repository Settings
- Navigate to your GitHub repository
- Click on Settings in the repository menu
- Navigate to Environments in the left sidebar
3.2 Configure Environment Secrets
Create or update the environment (e.g., staging, production) and add the following secrets:
- Database Connection Strings: PostgreSQL connection details
- API Keys: External service API keys
- JWT Secrets: Authentication token secrets
- Encryption Keys: Data encryption keys
- Third-party Service Credentials: Any required service credentials
The exact list of required secrets depends on your Admin Panel configuration. Refer to your application's environment variable documentation for the complete list.
3.3 Verify Secret Configuration
Ensure all required secrets are properly configured and accessible to your CI/CD pipeline.
Step 4: Verify Setup
4.1 Check Container Status
Verify all containers are running:
docker ps
You should see:
nginx-admin-panelcontainer running- Admin Panel application container running (if already deployed)
4.2 Test HTTPS Access
Test access to the Admin Panel via HTTPS:
curl -I https://admin.example.com
You should receive a 200 OK or 301/302 redirect response.
4.3 Verify SSL Certificate
Verify that SSL is properly configured:
openssl s_client -connect admin.example.com:443 -servername admin.example.com
4.4 Check Nginx Logs
Monitor Nginx logs for any errors:
docker logs -f nginx-admin-panel
Troubleshooting
Common Issues
Nginx container fails to start
- Verify Docker network exists:
docker network ls - Check if ports 80 and 443 are already in use:
sudo netstat -tulpn | grep -E ':(80|443)' - Verify SSL certificate paths and permissions
SSL certificate errors
- Ensure certificate files are in the correct format (PEM)
- Verify certificate and key match:
openssl x509 -noout -modulus -in certs/certificate.crt | openssl md5andopenssl rsa -noout -modulus -in certs/private.key | openssl md5 - Check certificate expiration:
openssl x509 -in certs/certificate.crt -noout -dates
502 Bad Gateway errors
- Verify the Admin Panel container is running:
docker ps - Check if the container name and port in nginx.conf match the actual service
- Verify Docker network connectivity:
docker network inspect sbmcrm-network
Connection timeouts
- Verify firewall rules allow traffic on ports 80 and 443
- Check security group settings in your cloud provider
- Verify domain DNS points to the correct IP address
Next Steps
After completing the initial setup:
- Deploy the Admin Panel: Follow the Admin Panel Deployment Guide to deploy your first version
- Configure Monitoring: Set up monitoring and logging as described in the Monitoring Setup Guide
- Review Security: Review and implement additional security measures from the SSL Security Guide