# Getting Started

***

### Prerequisites

| Component | Minimum | Recommended   | Notes                         |
| --------- | ------- | ------------- | ----------------------------- |
| Docker    | 20.10+  | 24.0+         | Auto-installed if missing     |
| Rust      | 1.70+   | Latest stable | For backend compilation       |
| Node.js   | 18.0+   | 20.0+ LTS     | For frontend and privacy mode |

NØXTERM can automatically install Docker and Node.js on most platforms. See Auto-Setup for details.

***

### Installation

#### Clone and Build

```bash
# Clone the repository
git clone https://github.com/NON-OS/noxterm.git
cd noxterm

# Build the backend
cd nox-backend
cargo build --release

# Build the frontend
cd ../frontend
npm install
npm run build
```

***

#### Start the Services

**Terminal 1: Backend**

```bash
cd nox-backend
cargo run --release
```

The backend starts on `http://0.0.0.0:3001` by default.

**Terminal 2: Frontend (Development)**

```bash
cd frontend
npm run dev
```

The frontend development server starts on `http://localhost:5173`.

#### Verify Installation

```bash
# Check backend health
curl http://localhost:3001/health

# Expected response:
# {"status":"healthy","timestamp":"..."}
```

Open `http://localhost:5173` in your browser to access the terminal interface.

***

### First Session

#### `Creating a Terminal`

1. Enter a username (alphanumeric, underscores, hyphens allowed)
2. Select a container image from the dropdown:

ArchLinux, Ubuntu 24.04-22.04,  Alpine, Debian. 

#### `Click "Create Terminal Session"` 

The container spawns within seconds. You'll see a bash prompt ready for input.

#### Basic Commands

```bash
# Verify your environment
uname -a
cat /etc/os-release

# Check available resources
free -h
df -h

# Install packages (will not persist after session)
apt update && apt install -y curl htop vim

# Test network connectivity
curl https://httpbin.org/ip

# Run interactive applications
htop
vim test.txt
```

***

#### Terminal Features

**`Copy/Paste`**

* Copy: Select text with mouse, use Ctrl+C (or Cmd+C on macOS)
* Paste: Ctrl+V (or Cmd+V on macOS)

**`Terminal Resize`**

* The terminal automatically resizes when you resize your browser window
* Interactive applications (vim, htop) respond to resize events

**`Interactive Editors`**

* `nano filename` - Simple text editor, Ctrl+X to exit
* `vim filename` - Modal editor, `:wq` to save and quit

***

### Session Management

#### `Multiple Sessions`

Each user can run up to 3 concurrent containers. Create additional sessions by opening new browser tabs and creating terminals with the same username.

#### `Session Persistence`

If you close the browser tab or lose connection:

* The container continues running for a **grace period** (default: 5 minutes)
* Reopen the session URL or create a new session with the same ID to reattach
* After the grace period, the container is automatically destroyed

#### `Ending a Session`

Sessions end when:

* You explicitly terminate them via the UI
* The grace period expires after disconnection
* The backend process restarts
* Resource limits are exceeded

***

### Auto-Setup

NØXTERM can automatically install missing dependencies.

#### `Docker Auto-Installation`

**macOS**

* Installs Colima (lightweight Docker alternative) via Homebrew
* Falls back to Docker Desktop installation prompt

**Linux**

* Uses official Docker installation script
* Supports apt, dnf, yum, and pacman package managers

**Windows**

* Prompts for manual installation (cannot auto-install GUI applications)
* Supports Docker Desktop or WSL2 with Docker

#### `Node.js Auto-Installation`

Required only for privacy mode. When you enable privacy:

**macOS**

* Homebrew: `brew install node`
* Falls back to nvm if Homebrew unavailable

**Linux**

* NodeSource repository for apt-based systems
* Package manager installation for others

**Windows**

* winget, Chocolatey, or Scoop

***

### Development Mode

For active development with hot reload:

**Backend**

```bash
cd nox-backend
RUST_LOG=noxterm=debug cargo run
```

**Frontend**

```bash
cd frontend
npm run dev
```

The frontend dev server proxies API requests to the backend automatically.

***

### Production Deployment

#### Build Optimized Binaries

```bash
# Backend (release build with optimizations)
cd nox-backend
cargo build --release
# Binary: target/release/noxterm-backend

# Frontend (production build)
cd frontend
npm run build
# Static files: dist/
```

#### Docker Deployment

```bash
# Build frontend container
docker build -f frontend/Dockerfile -t noxterm-frontend:latest .

# Run with custom configuration
DATABASE_URL=postgresql://user:pass@localhost/noxterm \
SERVER_PORT=3001 \
ENVIRONMENT=production \
./target/release/noxterm-backend
```

#### Reverse Proxy Configuration

For production, run behind nginx or Caddy for HTTPS termination:

**nginx example**

```nginx
server {
    listen 443 ssl http2;
    server_name terminal.example.com;

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

    # Frontend static files
    location / {
        root /var/www/noxterm/dist;
        try_files $uri $uri/ /index.html;
    }

    # Backend API
    location /api {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket endpoints
    location ~ ^/(ws|pty)/ {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }

    # Health checks
    location /health {
        proxy_pass http://127.0.0.1:3001;
    }
}
```

### Troubleshooting

#### Docker Not Found

```
Error: Docker socket not found
```

**Solution:** Install Docker and ensure the daemon is running.

* macOS: Install Docker Desktop or Colima
* Linux: `sudo systemctl start docker`
* Windows: Start Docker Desktop

#### Container Creation Fails

```
Error: Failed to create container
```

**Possible causes:**

* Docker daemon not running
* Image not available (will auto-pull on first use)
* Resource limits exceeded on host
* Disk space full

#### WebSocket Connection Failed

```
Error: WebSocket connection failed
```

**Check:**

* Backend is running on expected port
* No firewall blocking WebSocket connections
* Reverse proxy configured for WebSocket upgrade

#### Permission Denied

```
Error: Permission denied connecting to Docker socket
```

**Solution:** Add your user to the docker group:

```bash
sudo usermod -aG docker $USER
# Log out and back in
```