grokway/docs/how_deploy_prod.md

# Deploying GrokwayV2 to Production

This guide explains how to deploy the **GrokwayV2 Server** using Docker and Docker Compose.

## Prerequisites

- A Linux server (Ubuntu/Debian recommended) with a public IP.
- **Docker** and **Docker Compose** installed.
- A domain name (e.g., `example.com`) pointing to your server's IP.
- **Wildcard DNS** configured (e.g., `*.example.com` -> Server IP) to support dynamic subdomains.

## 1. Installation

1. **Clone the repository** (or copy the files) to your server:
   ```bash
   git clone <repository-url>
   cd GrokwayV2
   ```

2. **Verify Configuration**
   - Ensure `Dockerfile` and `docker-compose.yml` are present.
   - The default configuration uses ports `2222` (SSH) and `8080` (HTTP). Open these ports in your firewall (e.g., Security Groups, UFW).

## 2. Deploy with Docker Compose

Run the following command to build and start the server in detached mode:

```bash
docker-compose up -d --build
```

### Verify Status
Check if the container is running:
```bash
docker-compose ps
```

Check logs:
```bash
docker-compose logs -f
```

## 3. Client Connection

Clients can now connect to your server using the public IP or domain.

**Command:**
```bash
# If running locally (dev)
go run cmd/client/main.go --server example.com:2222 --local <local-port>

# If using a compiled binary
./grokway-client --server example.com:2222 --local <local-port>
```

> **Note:** Ensure the client points to port `2222` (or your mapped SSH port).

## 4. Updates

To deploy a new version:

1. Pull the latest code:
   ```bash
   git pull origin main
   ```
2. Rebuild and restart:
   ```bash
   docker-compose up -d --build
   ```

## Troubleshooting

- **Connection Refused:** Check if ports 2222 and 8080 are open in the firewall.
- **DNS Issues:** Ensure your wildcard DNS (`*.example.com`) is correctly propagating.
- **Permission Denied:** Ensure your user has rights to run docker commands (add user to docker group).

## Nginx Configuration

Since you already have `api.orin.remote.band` configured, you can add a new configuration for the main application and its subdomains.

### 1. HTTP/HTTPS Configuration (sites-available)

Create a new file `/etc/nginx/sites-available/grokway`:

```nginx
server {
    # Main domain and wildcard subdomains
    server_name grokway.orin.remote.band *.grokway.orin.remote.band;
    
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        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 $scheme;
        
        # WebSocket support (important for future interactive features)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    listen 80;
}
```

Enable it:
```bash
ln -s /etc/nginx/sites-available/grokway /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx
```

**SSL Certificate (Crucial Step):**

To support dynamic subdomains (e.g., `client1.grokway.orin.remote.band`), you **MUST** obtain a **Wildcard Certificate**. A standard certificate for `grokway.orin.remote.band` is **NOT valid** for its subdomains.

You need a certificate that covers both:
1. `grokway.orin.remote.band`
2. `*.grokway.orin.remote.band`

**How to get a Wildcard Certificate with Certbot:**
Wildcard certificates require **DNS validation** (you cannot use HTTP validation).

```bash
# Request a wildcard certificate
sudo certbot certonly --manual --preferred-challenges dns -d "grokway.orin.remote.band" -d "*.grokway.orin.remote.band"
```

1. Run the command.
2. Certbot will ask you to create a specific **TXT record** in your DNS provider (where you manage `orin.remote.band`).
3. Create the TXT record as instructed.
4. Wait a minute for propagation, then press Enter.

Once obtained, update your Nginx config (`/etc/nginx/sites-available/grokway`) to use the new certificates.

**Full Configuration with SSL:**

```nginx
server {
    server_name grokway.orin.remote.band *.grokway.orin.remote.band;

    # SSL Configuration
    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/grokway.orin.remote.band/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/grokway.orin.remote.band/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        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 $scheme;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# Redirect HTTP to HTTPS
server {
    if ($host = grokway.orin.remote.band) {
        return 301 https://$host$request_uri;
    }
    # Also redirect subdomains if needed, or use a wildcard match here

    listen 80;
    server_name grokway.orin.remote.band *.grokway.orin.remote.band;
    return 404;
}
```

### 2. SSH Proxy Configuration (nginx.conf)

**Important:** The SSH proxy uses the `stream` module. This block **CANNOT** go inside `sites-available` (which are included inside the `http` block). It must go at the top level of `/etc/nginx/nginx.conf`.

Edit `/etc/nginx/nginx.conf` and add this **at the very end of the file**, outside of any `http {}` block:

```nginx
stream {
    upstream grokway_ssh {
        # Forward to the internal port where Grokway server is running (e.g., 2223)
        server 127.0.0.1:2223;
    }

    server {
        listen 2222; # Public facing SSH port
        proxy_pass grokway_ssh;
    }
}
```

After changing `nginx.conf`:
```bash
nginx -t
systemctl reload nginx
```

### 3. Run the Server

Since Nginx is now listening on port `2222` (public), you must run the Grokway server on a **different internal port** (e.g., `2223`) to avoid conflicts.

Running locally with Go:
```bash
go run cmd/server/main.go -ssh :2223
```

Running with Docker (update `docker-compose.yml`):
- Ensure the container exposes/maps port `2223` internally if needed, or simply let it run on default but map `2223:2222`? 
- Actually, better just pass the arg:
```bash
command: ["/app/grokway-server", "-ssh", ":2223"]
```
And update ports mapping:
```yaml
ports:
  - "127.0.0.1:2223:2223" # Only bind to localhost if Nginx is proxying
```