# CK-X Simulator: Development Setup Guide This document provides step-by-step instructions for setting up and running the CK-X Simulator locally for development purposes. ## Prerequisites ### System Requirements - **Operating System**: Linux, macOS, or Windows 10/11 with WSL2 - **CPU**: 4+ cores recommended (minimum 2 cores) - **RAM**: 8GB minimum, 16GB recommended - **Storage**: 20GB free space ### Required Software - **Docker**: v20.10.0 or newer - **Docker Compose**: v2.0.0 or newer ## Installation Steps ### 1. Clone the Repository ```bash git clone https://github.com/your-org/ck-x-simulator.git cd ck-x-simulator ``` ### 2. Configure the Environment Review the `compose.yaml` file to understand the service configuration. Key services include: - **remote-desktop**: VNC server (Ubuntu) - **webapp**: Web Application frontend - **nginx**: Reverse proxy (only service exposed to users) - **jumphost**: SSH access host - **remote-terminal**: Remote terminal service - **k8s-api-server**: KIND Kubernetes cluster - **redis**: Redis database for Facilitator - **facilitator**: Backend service ### 3. Start the Services ```bash # Build and start all services docker-compose up --build ``` This command will build and start all the services defined in the compose.yaml file. ## Accessing the Application ### 1. Web Interface Once all services are running, access the web interface via Nginx: ``` http://localhost:30080 ``` ### 2. VNC Remote Desktop The VNC server is not directly exposed outside the container network. To access it: 1. The web interface proxies VNC connections through Nginx 2. Default VNC password: `bakku-the-wizard` (configured in compose.yaml) 3. VNC resolution: 1280x800 ### 3. SSH Access SSH access is provided through the jumphost service: - **Hostname**: ckad9999 - **Username**: candidate - **Password**: password (configured in compose.yaml) The SSH service is not directly exposed outside the container network and is accessed through the webapp. ## Service Details ### 1. Remote Desktop (VNC) ```yaml # From compose.yaml remote-desktop: image: nishanb/ck-x-simulator-remote-desktop:latest hostname: terminal expose: - "5901" # VNC port (internal only) - "6901" # Web VNC port (internal only) environment: - VNC_PW=bakku-the-wizard - VNC_PASSWORD=bakku-the-wizard - VNC_VIEW_ONLY=false - VNC_RESOLUTION=1280x800 ``` The remote desktop provides a graphical interface for the exam environment. ### 2. Web Application ```yaml # From compose.yaml webapp: image: nishanb/ck-x-simulator-webapp:latest expose: - "3000" # Only exposed to internal network environment: - VNC_SERVICE_HOST=remote-desktop - VNC_SERVICE_PORT=6901 - VNC_PASSWORD=bakku-the-wizard - SSH_HOST=remote-terminal - SSH_PORT=22 - SSH_USER=candidate - SSH_PASSWORD=password ``` The web application serves as the frontend interface for the simulator. ### 3. Nginx (Reverse Proxy) ```yaml # From compose.yaml nginx: image: nishanb/ck-x-simulator-nginx:latest ports: - "30080:80" # Expose Nginx on port 30080 ``` Nginx is the only service directly exposed to users and handles routing to internal services. ### 4. Kubernetes Cluster ```yaml # From compose.yaml k8s-api-server: image: nishanb/ck-x-simulator-cluster:latest container_name: kind-cluster hostname: k8s-api-server privileged: true # Required for running containers inside KIND expose: - "6443:6443" - "22" volumes: - kube-config:/home/candidate/.kube # Shared volume for Kubernetes config ``` The Kubernetes cluster runs in a KIND container with shared kube-config volume. ### 5. Facilitator Service ```yaml # From compose.yaml facilitator: image: nishanb/ck-x-simulator-facilitator:latest hostname: facilitator expose: - "3000" ports: - "3001:3000" environment: - PORT=3000 - NODE_ENV=prod - SSH_HOST=jumphost - SSH_PORT=22 - SSH_USERNAME=candidate - LOG_LEVEL=info - REDIS_HOST=redis - REDIS_PORT=6379 ``` The facilitator service handles backend operations and communicates with the Kubernetes cluster. ## Development Workflow ### 1. Modifying Services To modify a service, edit its corresponding directory and then rebuild: ```bash # Edit files in the respective service directory # Then rebuild and restart the service docker-compose up --build ``` ### 2. Inspecting Logs ```bash # View logs for all services docker-compose logs # View logs for a specific service docker-compose logs # Follow logs docker-compose logs -f ``` ### 3. Accessing Containers ```bash # Get shell access to a container docker-compose exec bash # Examples: docker-compose exec webapp bash docker-compose exec facilitator bash docker-compose exec k8s-api-server bash ``` ## Troubleshooting ### 1. Container Startup Issues If containers fail to start, check the logs: ```bash docker-compose logs ``` ### 2. VNC Connection Issues ```bash # Check if VNC server is running docker-compose exec remote-desktop ps aux | grep vnc # Restart VNC service docker-compose restart remote-desktop ``` ### 3. Kubernetes Cluster Issues ```bash # Check cluster status docker-compose exec k8s-api-server kubectl cluster-info # Restart the cluster docker-compose restart k8s-api-server ``` ### 4. Resource Constraints If your system cannot handle the resource requirements, adjust the limits in compose.yaml: ```yaml deploy: resources: limits: cpus: '1' # Reduce CPU allocation memory: 1G # Reduce memory allocation ``` ## Network Architecture All services are connected through the `ckx-network` bridge network: ```yaml networks: ckx-network: name: ckx-network driver: bridge ``` Services can communicate with each other using their service names as hostnames. ## Volume Management The system uses persistent volumes for: ```yaml volumes: kube-config: # Shared volume for Kubernetes configuration redis-data: # Persistent volume for Redis data ``` ## Reference Links - [Docker Compose Documentation](https://docs.docker.com/compose/) - [Kubernetes Documentation](https://kubernetes.io/docs/) - [KIND Documentation](https://kind.sigs.k8s.io/) - [VNC Documentation](https://www.realvnc.com/en/connect/docs/)