MKS DevEnv
Getting Started

Installation

Complete installation guide for MKS DevEnv

Installation

Complete installation guide for MKS DevEnv on your local machine or VPS.

System Requirements

Minimum Requirements

ComponentMinimumRecommended
RAM4GB8GB+
Disk Space20GB50GB+
CPU2 cores4+ cores
Dockerv20.10+Latest
Docker Composev2.0+Latest

Operating System

  • macOS: 11+ (Big Sur or later)
  • Windows: 10/11 with WSL2
  • Linux: Ubuntu 20.04+, Debian 11+, or compatible

Installation Methods

Quick Start Installation

Clone the repository:

git clone https://github.com/MKS2508/mks-dev-environment.git
cd mks-dev-environment/docker

Create environment file:

cp .env.example .env

Edit .env with your preferred editor:

# Required passwords
CODE_SERVER_PASSWORD=your_secure_password
RDP_PASSWORD=your_secure_password
VNC_PASSWORD=your_secure_password

# Database
GUACAMOLE_DB_NAME=guacamole_db
GUACAMOLE_DB_USER=guacamole_user
GUACAMOLE_DB_PASSWORD=your_db_password

# SSH (optional but recommended)
SSH_PUBLIC_KEY="ssh-rsa AAAA... your@email.com"

# GitHub (optional)
GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Display
VNC_RESOLUTION=1920x1080
VNC_DEPTH=24

# Timezone
TZ=America/New_York

Security: Always use strong, unique passwords. The defaults should be changed for production use.

Start all services:

docker compose up -d

This will pull images and start:

  • devenv-full (desktop environment)
  • guacamole-postgres (database)
  • guacamole-guacd (proxy daemon)
  • guacamole (web interface)

Initialize Guacamole database:

cd guacamole
chmod +x init.sh
./init.sh

This creates the database schema and a default RDP connection.

Verify installation:

# Check all services are running
docker compose ps

# Check service health
docker compose ps

All services should show "Up" or "healthy" status.

Access your environment:

Coolify VPS Deployment

Deploy to a VPS with automatic HTTPS via Coolify.

Push to GitHub:

git add .
git commit -m "Ready for Coolify deployment"
git push origin master

Connect repository in Coolify:

  1. Open Coolify dashboard
  2. Click New Application
  3. Select Git (GitHub)
  4. Connect your repository
  5. Select branch: master

Configure application:

  • Name: mks-dev-environment
  • Build Pack: Docker Compose
  • Base Directory: /docker
  • Docker Compose Location: /docker-compose.yaml

Configure domains:

ServiceDomain Example
devenvdevenv.your-domain.com
guacamoleguacamole.your-domain.com

Traefik will automatically generate SSL certificates.

Add environment variables in Coolify secrets:

  • CODE_SERVER_PASSWORD
  • RDP_PASSWORD
  • GUACAMOLE_DB_PASSWORD
  • SSH_PUBLIC_KEY
  • GITHUB_TOKEN

Deploy and verify:

  1. Click Deploy
  2. Wait for build and health checks
  3. Access via configured domains

Manual VPS Installation

Deploy directly to a VPS with manual SSL configuration.

Connect to your VPS:

ssh root@your-vps-ip

Install Docker:

curl -fsSL https://get.docker.com | sh
usermod -aG docker $USER

Log out and back in for group changes to take effect.

Clone repository:

cd /opt
git clone https://github.com/MKS2508/mks-dev-environment.git
cd mks-dev-environment/docker

Configure environment:

cp .env.example .env
nano .env
# Edit with your passwords and configuration

Start services:

docker compose up -d

Initialize Guacamole:

cd guacamole
chmod +x init.sh
./init.sh

Configure SSL (optional but recommended):

Using Nginx reverse proxy:

server {
    listen 443 ssl;
    server_name guacamole.your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Environment Variables Reference

Required Variables

VariableDescriptionExample
CODE_SERVER_PASSWORDCode-Server authenticationSecurePass123!
RDP_PASSWORDRDP/xrdp authenticationSecurePass123!
GUACAMOLE_DB_PASSWORDPostgreSQL passwordDbPass456!

Optional Variables

VariableDescriptionDefault
VNC_PASSWORDVNC authentication (legacy)devenv
GUACAMOLE_DB_NAMEDatabase nameguacamole_db
GUACAMOLE_DB_USERDatabase userguacamole_user
SSH_PUBLIC_KEYPublic SSH key-
GITHUB_TOKENGitHub PAT-
VNC_RESOLUTIONDisplay resolution1920x1080
VNC_DEPTHColor depth (16 or 24)24
TZTimezoneEurope/Madrid

Port Mapping

Host PortContainerServiceNotes
222222SSHChanged from 22 to avoid conflict
33893389RDPStandard RDP port
80818080GuacamoleChanged for Coolify compatibility
84438443Code-ServerStandard HTTPS alternative

Port Conflicts: If you have services running on these ports, update the port mappings in docker-compose.yaml.

Post-Installation Steps

Change Guacamole Admin Password

  1. Login to Guacamole: http://localhost:8081/guacamole
  2. Use default credentials: guacadmin / guacadmin
  3. Go to Settings → Users
  4. Change the admin password immediately
# Generate SSH key if you don't have one
ssh-keygen -t ed25519 -C "your@email.com"

# Copy public key
cat ~/.ssh/id_ed25519.pub

# Add to .env
SSH_PUBLIC_KEY="ssh-ed25519 AAAA... your@email.com"

# Restart devenv container
docker compose restart devenv

Verify All Services

# Check service status
docker compose ps

# Test endpoints
curl -f http://localhost:8081/guacamole
curl -f http://localhost:8443/healthz

# Check logs
docker compose logs -f

Upgrading

To upgrade to the latest version:

# Pull latest changes
git pull origin master

# Rebuild and restart
docker compose up -d --build

# Re-initialize Guacamole if needed
cd guacamole && ./init.sh

Uninstallation

To completely remove DevEnv:

WARNING: This deletes all data, volumes, and configurations!

# Stop all services
docker compose down

# Remove all volumes (DELETES DATA)
docker volume rm $(docker volume ls -q)

# Remove images
docker rmi $(docker images -q mks-devenv-*)

Troubleshooting

Port Already in Use

# Find what's using the port
sudo lsof -i :8081

# Stop conflicting service or change port in docker-compose.yaml

Permission Denied

# Check Docker permissions
groups $USER

# Add user to docker group
sudo usermod -aG docker $USER

# Re-login for changes to take effect

Out of Memory

# Increase Docker memory limit (Docker Desktop settings)
# Or add memory limit to docker-compose.yaml

See Troubleshooting for more help.

Next Steps

Getting Started

Introduction to MKS DevEnv - Containerized development environment

Quick Start

Get DevEnv Pro up and running in minutes

Actions

On this page

InstallationSystem RequirementsMinimum RequirementsOperating SystemInstallation MethodsQuick Start InstallationCoolify VPS DeploymentManual VPS InstallationEnvironment Variables ReferenceRequired VariablesOptional VariablesPort MappingPost-Installation StepsChange Guacamole Admin PasswordConfigure SSH Key (Optional but Recommended)Verify All ServicesUpgradingUninstallationTroubleshootingPort Already in UsePermission DeniedOut of MemoryNext Steps