Complete Infrastructure Project Documentation
Very detailed project document covering Docker, Kubernetes, Nginx, DNS, SSL, load balancing, monitoring, packet flow, troubleshooting and future expansion.
1. Executive Summary
This project builds a production-style infrastructure platform on a single Ubuntu VPS. The goal is not only to host a website, but to understand how modern infrastructure is assembled using Docker, Kubernetes concepts, Nginx reverse proxying, DNS, SSL, monitoring, load balancing and live status dashboards.
The VPS currently runs a Docker-based platform with Nginx as the public entry point. The public IP address is 5.39.37.7. Users opening the public IP see a live infrastructure dashboard that reads actual server information such as CPU, memory, disk, Docker containers, network interfaces, installed packages and service state.
Kubernetes files and a kubeadm installation script are prepared, but kubeadm is intentionally not initialized on this host because the VPS is detected as an LXC container. kubeadm requires a full VM or bare-metal host with complete cgroup, iptables, bridge networking and kernel module control.
2. Business and Learning Use Case
The practical use case is a network engineer learning how cloud-native infrastructure works by building a reusable platform. Instead of learning Docker, Nginx, DNS, SSL, Kubernetes and monitoring separately, this project connects all of them into one working system.
Future applications can include:
• Company website
• Customer portal
• API gateway
• NGFW/firewall product portal
• ERP platform
• Trading platform
• Documentation portal
• Download center
• Monitoring portal
• Private admin tools
The key real-world problem solved here is hosting multiple services and future domains on one VPS with one public IPv4 address. This is done by using DNS records, Nginx virtual hosts, reverse proxying and later Kubernetes Ingress.
3. Current Server Inventory
Current observed environment:
Operating System: Ubuntu 24.04 LTS Public IP: 5.39.37.7 Access: root SSH Virtualization: LXC Web entry: Nginx Container runtime:Docker Engine Monitoring: Prometheus, Grafana, Node Exporter Management: Portainer Dashboard: Flask application inside Docker Docs path: /opt/cloud-platform/docs App path: /opt/cloud-platform/dashboard Monitoring path: /opt/cloud-platform/monitoring Kubernetes path: /opt/cloud-platform/k8s Scripts path: /opt/cloud-platform/scripts
Important implication of LXC:
systemd-detect-virt -> lxc br_netfilter -> unavailable inside guest
This means the current VPS can run Docker, Nginx and monitoring, but a proper kubeadm Kubernetes cluster should be built on a full VM.
4. High-Level Architecture
The platform uses Nginx as the public edge layer. Docker containers run private services. Monitoring is also containerized. Documentation is served as static files through Nginx.
Internet User
|
| HTTP or HTTPS
v
Public IP: 5.39.37.7
|
v
Nginx Reverse Proxy
|
+-- / -> cloud-dashboard container on 127.0.0.1:8080
+-- /docs/ -> static documentation in /opt/cloud-platform/docs
+-- /grafana/ -> grafana container on 127.0.0.1:3000
+-- /prometheus/ -> prometheus container on 127.0.0.1:9090
+-- /portainer/ -> portainer container on 127.0.0.1:9000
|
+-- future domains -> Kubernetes Ingress Controller
-> Kubernetes Services
-> Pods
Design principles:
• Public traffic enters through Nginx only.
• Containers are not directly exposed except where intentionally needed.
• Internal services bind to localhost where possible.
• Monitoring runs independently from the dashboard.
• Documentation is separate from the dashboard application.
• Kubernetes is prepared as a future orchestration layer.
5. Request Flow: Browser to Dashboard
When a user opens `http://5.39.37.7/`, the request follows this path:
1. Browser creates TCP connection to 5.39.37.7:80. 2. The packet reaches the VPS network interface. 3. Linux TCP/IP stack passes the connection to Nginx. 4. Nginx matches location /. 5. Nginx proxies the request to http://127.0.0.1:8080. 6. Docker port mapping forwards traffic to cloud-dashboard container. 7. Flask receives the HTTP request. 8. Flask reads live server information from mounted host paths and Docker socket. 9. Flask renders the dashboard HTML. 10. Response returns through Docker -> Nginx -> browser.
For HTTPS, Nginx also performs TLS handling:
Browser -> TLS handshake -> Nginx certificate -> encrypted HTTP -> Nginx decrypts -> internal HTTP proxy
Currently HTTPS uses a self-signed certificate because no domain has been purchased yet.
6. Docker Detailed Explanation
Docker is used as the container runtime. A container is an isolated process with its own filesystem, libraries and runtime dependencies. Containers share the host kernel but run in separate namespaces.
Namespaces involved in containers:
• PID namespace: isolated process IDs
• Network namespace: isolated interfaces and routing
• Mount namespace: isolated filesystem mounts
• UTS namespace: hostname isolation
• IPC namespace: isolated inter-process communication
• User namespace: optional user mapping
Docker components in this project:
Docker Engine -> daemon managing containers Docker CLI -> command-line control Docker Compose -> multi-service application definitions Docker networks -> private communication between containers Docker volumes -> persistent data storage Docker socket -> API used by dashboard to read container status
Current containers:
cloud-dashboard live infrastructure dashboard portainer Docker web management UI prometheus metrics collection database grafana metrics visualization node-exporter host metrics exporter
Useful Docker commands:
docker ps docker ps -a docker images docker inspect cloud-dashboard docker logs cloud-dashboard docker network ls docker network inspect cloud_platform_net docker volume ls cd /opt/cloud-platform/dashboard && docker compose up -d --build cd /opt/cloud-platform/monitoring && docker compose up -d
7. Docker Networking Deep Dive
Docker networking allows containers to communicate with each other and with the host.
Typical path for the dashboard:
Nginx process on host -> 127.0.0.1:8080 -> Docker published port -> container network namespace -> gunicorn process inside cloud-dashboard
The private Docker network `cloud_platform_net` is used to group platform containers. Docker bridge networking creates a virtual switch on the host. Containers attach to this bridge through virtual ethernet pairs.
Docker bridge concept:
Container eth0 -> veth pair -> Docker bridge -> host network namespace -> Nginx or external network
Why private container networking matters:
• Reduces public attack surface
• Keeps service-to-service traffic internal
• Allows Nginx to act as the single control point
• Makes future migration to Kubernetes easier
8. Nginx Reverse Proxy Detailed Explanation
Nginx is the public web server and reverse proxy. A reverse proxy receives client requests and forwards them to backend services.
Forward proxy vs reverse proxy:
Forward proxy: client-side proxy used to access the internet. Reverse proxy: server-side proxy used to expose internal applications.
Current Nginx roles:
• Listen on port 80 for HTTP
• Listen on port 443 for HTTPS
• Serve dashboard at `/`
• Serve documentation at `/docs/`
• Proxy Grafana at `/grafana/`
• Proxy Prometheus at `/prometheus/`
• Proxy Portainer at `/portainer/`
• Prepare for future virtual hosts
Important headers:
Host original hostname requested by browser X-Real-IP original client IP X-Forwarded-For chain of proxy IPs X-Forwarded-Proto http or https
These headers are important because backend applications may need to generate correct links, know whether the original request was HTTPS and log the real client IP.
9. DNS Detailed Explanation
DNS translates domain names into IP addresses. Without DNS, users need to remember public IP addresses.
A record:
vaishaktech.com A 5.39.37.7
This tells the world that `vaishaktech.com` resolves to the VPS public IPv4 address.
CNAME record:
www.vaishaktech.com CNAME vaishaktech.com
This means `www.vaishaktech.com` is an alias for `vaishaktech.com`.
Multiple domains on one IP:
vaishaktech.com -> 5.39.37.7 vaishaklabs.com -> 5.39.37.7 vpnetwork.io -> 5.39.37.7 myfirewall.in -> 5.39.37.7
When the browser sends an HTTP request, it includes a Host header:
GET / HTTP/1.1 Host: vaishaktech.com
Nginx reads this Host header and selects the matching virtual host configuration.
10. SSL and HTTPS Detailed Explanation
HTTP sends data in plain text. HTTPS encrypts HTTP traffic using TLS.
TLS handshake simplified:
1. Browser connects to server on port 443. 2. Server sends certificate. 3. Browser validates certificate trust and hostname. 4. Browser and server agree on encryption keys. 5. HTTP traffic is exchanged inside encrypted TLS session.
Current state:
• HTTPS is active on the public IP.
• Certificate is self-signed.
• Browser may show a warning.
Why browser warning happens:
• The certificate is not issued by a trusted public Certificate Authority.
• Public CAs normally validate domain names, not temporary raw IP access.
Future trusted SSL flow:
1. Buy domain. 2. Point DNS A record to 5.39.37.7. 3. Run Certbot. 4. Let's Encrypt validates the domain. 5. Nginx receives trusted certificate files. 6. Browser shows secure lock without warning.
Prepared command:
/opt/cloud-platform/scripts/issue-ssl-certificates.sh
11. Kubernetes Detailed Explanation
Kubernetes is the future orchestration layer. It is used when applications need scaling, self-healing, rolling updates and service discovery.
Core Kubernetes objects:
Pod smallest deployable unit Deployment desired state and rollout controller ReplicaSet keeps the requested number of Pods alive Service stable endpoint and internal load balancer Ingress HTTP routing by hostname/path ConfigMap non-secret configuration Secret sensitive configuration Namespace logical separation Node worker machine in the cluster
Why Kubernetes is prepared but not initialized:
The current VPS is LXC. kubeadm needs full kernel and networking control. The required `br_netfilter` module is unavailable in the guest. Running kubeadm here would likely fail preflight checks or create an unstable cluster.
Prepared files:
/opt/cloud-platform/k8s/namespace.yaml /opt/cloud-platform/k8s/website.yaml /opt/cloud-platform/k8s/api.yaml /opt/cloud-platform/k8s/ingress.yaml /opt/cloud-platform/scripts/install-kubeadm-single-node.sh
Future kubeadm flow on a full VM:
1. Disable swap. 2. Load overlay and br_netfilter modules. 3. Configure sysctl networking. 4. Configure containerd systemd cgroup driver. 5. Install kubelet, kubeadm and kubectl. 6. Run kubeadm init. 7. Install CNI plugin such as Flannel or Calico. 8. Deploy ingress controller. 9. Apply application manifests.
12. Kubernetes Networking Detailed Explanation
Kubernetes networking is different from Docker Compose networking.
Kubernetes traffic path:
External request -> Ingress Controller -> Ingress rule -> Kubernetes Service -> EndpointSlice -> Pod IP -> container port
Service types:
ClusterIP internal-only virtual IP NodePort exposes service on every node port LoadBalancer asks cloud provider for external load balancer ExternalName DNS alias to external service
For this VPS project, Ingress is the best learning target because it demonstrates hostname-based routing similar to Nginx virtual hosts.
Example scaling:
kubectl scale deployment website -n cloud-platform --replicas=5
After scaling, the Service load balances traffic across all healthy Pod replicas.
13. Load Balancing Detailed Explanation
Load balancing distributes traffic across multiple backend instances.
Round robin:
Request 1 -> backend A Request 2 -> backend B Request 3 -> backend C Request 4 -> backend A
Least connections:
New request -> backend with fewest active connections
Health check:
Load balancer checks backend health endpoint. If backend fails, traffic stops going there. When backend recovers, traffic resumes.
Failover:
Primary backend fails -> standby backend receives traffic
Sticky sessions:
Same client -> same backend
Sticky sessions are useful for stateful apps, but a better production pattern is to store sessions in Redis or a database.
Nginx upstream example:
upstream website_pool {
server 127.0.0.1:8081;
server 127.0.0.1:8082;
server 127.0.0.1:8083;
}
location / {
proxy_pass http://website_pool;
}14. Monitoring Detailed Explanation
Monitoring answers these questions:
• Is the server alive?
• Is CPU high?
• Is memory exhausted?
• Is disk filling?
• Are containers running?
• Is network traffic abnormal?
• Are applications healthy?
Current monitoring components:
Node Exporter -> exports host metrics Prometheus -> scrapes and stores metrics Grafana -> visualizes metrics
Metrics flow:
Node Exporter /metrics endpoint -> Prometheus scrape job -> Prometheus time-series database -> Grafana datasource query -> dashboard panel
Useful checks:
curl http://127.0.0.1:9100/metrics curl http://127.0.0.1:9090/prometheus/-/healthy docker logs prometheus docker logs grafana docker logs node-exporter
Recommended Grafana dashboards later:
• Node Exporter Full dashboard
• Docker/container dashboard
• Nginx request dashboard
• Kubernetes cluster dashboard
• Application-specific dashboards
15. Infrastructure Dashboard Detailed Explanation
The dashboard is not a static website. It is a Flask application inside Docker.
It reads real status from:
/proc CPU, uptime, memory, network counters /sys/class/net network interface state /etc/os-release Ubuntu version /var/lib/dpkg/status installed packages /var/run/docker.sock Docker containers and version /etc/nginx/ssl SSL certificate presence
Routes:
/ dashboard HTML /api/status live JSON status /health health endpoint
Displayed items:
• Ubuntu version
• Public IP
• CPU usage
• Memory usage
• Disk usage
• Uptime
• Docker status
• Docker container count
• Kubernetes readiness
• SSL status
• Network interfaces
• Installed software
• Future domains
• Traffic flow explanations
This dashboard can later become the homepage for the purchased domain.
16. Documentation Portal Detailed Explanation
Documentation is intentionally separated from the dashboard.
Path:
/opt/cloud-platform/docs
Public route:
http://5.39.37.7/docs/ https://5.39.37.7/docs/
Reason for separate documentation pages:
• Dashboard stays focused on live infrastructure status.
• Documentation can be long and educational.
• Each topic can be linked independently.
• Future product docs can be added without redesign.
Current documentation pages include:
use-case.html architecture.html docker.html kubernetes.html nginx.html dns-ssl.html load-balancing.html monitoring.html dashboard.html packet-flow.html commands.html troubleshooting.html future.html full-documentation.html
17. Packet Flow Detailed View
HTTP packet flow:
Client ephemeral port -> destination 5.39.37.7:80 -> VPS eth interface -> Linux TCP stack -> Nginx worker -> proxy_pass to 127.0.0.1:8080 -> Docker port mapping -> container network namespace -> gunicorn -> Flask route
HTTPS packet flow:
Client ephemeral port -> destination 5.39.37.7:443 -> TLS handshake with Nginx -> encrypted HTTP request -> Nginx decrypts -> internal HTTP proxy to backend
Docker bridge flow:
Container process -> eth0 inside container -> veth pair -> Docker bridge -> host network namespace -> Nginx or external route
Future Kubernetes flow:
Ingress Controller -> Ingress object rule -> Service ClusterIP -> EndpointSlice -> Pod IP -> container port
18. Security Considerations
Current basic security posture:
• Nginx is the public web entry point.
• Most containers bind to localhost ports.
• HTTPS exists using a self-signed certificate.
• Portainer is available on port 9443.
Recommended improvements:
1. Change Grafana default password. 2. Set up firewall rules. 3. Restrict Portainer access by VPN or IP allowlist. 4. Use Let's Encrypt after domain purchase. 5. Disable direct root SSH password login and use SSH keys. 6. Add WireGuard VPN for admin access. 7. Keep Docker images updated. 8. Back up Docker volumes. 9. Add monitoring alerts. 10. Store secrets outside code and documentation.
Security is an ongoing process. This project is a learning platform and foundation, not a final hardened production environment yet.
19. Troubleshooting Guide
Grafana redirects to localhost:
Cause: wrong Grafana root_url/domain. Fix: set GF_SERVER_DOMAIN and GF_SERVER_ROOT_URL, then recreate container.
Nginx 502 Bad Gateway:
docker ps curl http://127.0.0.1:8080/health docker logs cloud-dashboard nginx -t
HTTPS browser warning:
Expected until real domain and Let's Encrypt certificate are used.
Kubernetes kubeadm failure:
Expected on LXC host. Use full VM.
Docs missing:
ls -l /opt/cloud-platform/docs nginx -t systemctl reload nginx curl http://127.0.0.1/docs/
Prometheus not scraping:
docker logs prometheus cat /opt/cloud-platform/monitoring/prometheus/prometheus.yml curl http://127.0.0.1:9100/metrics
20. Future Expansion Roadmap
Phase 1 completed:
• Docker Engine installed
• Docker Compose installed
• Portainer running
• Nginx reverse proxy running
• Dashboard running
• Prometheus/Grafana/Node Exporter running
• Documentation portal created
• HTTPS self-signed certificate enabled
Next recommended phases:
1. Buy domain name. 2. Add DNS A records to 5.39.37.7. 3. Run Let's Encrypt script. 4. Add firewall rules. 5. Add WireGuard VPN. 6. Add PostgreSQL. 7. Move Kubernetes to full VM. 8. Deploy Kubernetes ingress controller. 9. Add real websites and APIs. 10. Build CI/CD deployment pipeline. 11. Add Grafana dashboards and alerts. 12. Add backup strategy.
Future hosted products:
• NGFW management portal
• ERP portal
• Trading platform
• API gateway
• Customer login
• Documentation and download portal