> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wirekite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UX

> Run Wirekite migrations from the full-featured web interface.

## Overview

The Wirekite UX Server provides a web-based graphical interface for managing all aspects of database migrations. It allows you to configure sources and targets, run migrations, monitor progress in real-time, and validate data—all through your browser.

<Note>
  The UX Server runs on **HTTPS port 8443** by default and requires authentication.
</Note>

## Technology Stack

The UX Server is built with:

* **Backend:** Go with the Gin web framework
* **Frontend:** HTML/CSS/JavaScript with HTMX for dynamic updates
* **Charts:** Apache ECharts for real-time progress visualization
* **SQL Editor:** CodeMirror with syntax highlighting

## Getting Started

### Starting the UX Server

```bash theme={null}
# Start the UX server
cd /opt/wirekite/ux/server
./ux-server

# Or use systemd (recommended for production)
sudo systemctl start wirekite-ux
```

### Initial Setup

1. Open your browser and navigate to `https://your-server:8443`
2. On first access, you'll be redirected to the setup page
3. Create your root (admin) user account
4. Log in with your new credentials

<Warning>
  The initial root user can only be created once. Store these credentials securely.
</Warning>

## Main Features

### Dashboard

The main dashboard displays:

* All configured migrations with their current status
* Source and target database connections
* Quick access to tools and settings

### Migration Status Indicators

| Status              | Description                                      |
| ------------------- | ------------------------------------------------ |
| Migration Created   | Migration configured but schema not yet migrated |
| Schema Created      | Schema has been applied to target                |
| Data Loaded         | Initial data load completed                      |
| Replication Running | CDC replication is active                        |
| Replication Paused  | CDC replication is paused                        |

## Configuring Sources

Sources are the databases you extract data from. The GUI supports:

* **MySQL** - Host, port, username, password, database
* **PostgreSQL** - Host, port, username, password, database
* **Oracle** - Host, port, username, password, service name
* **SQL Server** - Host, port, username, password, database

### Creating a Source

1. Click **Sources** in the sidebar
2. Click **Add Source**
3. Select the database type
4. Fill in the connection parameters
5. Click **Test Connection** to verify
6. Click **Save**

## Configuring Targets

Targets are the databases you load data into. The GUI supports:

### On-Premise Targets

* MySQL
* PostgreSQL
* Oracle
* SQL Server
* SingleStore

### Cloud Targets

* Snowflake
* Firebolt
* Google BigQuery
* Google Cloud Spanner
* Databricks

### Cloud Target Configuration

Cloud targets require additional configuration for staging areas:

<ResponseField name="Snowflake" type="object">
  * Account identifier
  * Username and password
  * Database and warehouse
  * Role (optional)
</ResponseField>

<ResponseField name="Firebolt" type="object">
  * Account name
  * Client ID and secret
  * Engine name
  * AWS S3 bucket for staging
</ResponseField>

<ResponseField name="BigQuery" type="object">
  * GCP Project ID
  * Dataset name
  * GCS bucket for staging
</ResponseField>

<ResponseField name="Databricks" type="object">
  * Workspace host URL
  * Access token
  * SQL Warehouse ID
  * Catalog and schema
  * AWS S3 bucket for staging
</ResponseField>

<ResponseField name="Spanner" type="object">
  * GCP Project ID
  * Instance ID
  * Database ID
</ResponseField>

## Creating Migrations

A migration links a source to a target:

1. Click **Migrations** in the sidebar
2. Click **Create Migration**
3. Enter a migration name
4. Select the source database
5. Select the target database
6. Click **Create**

## Migration Workflow

### Step 1: Schema Migration

Extract and apply the schema from source to target:

1. Open your migration
2. Click **Schema** tab
3. Click **Extract Schema** to pull schema from source
4. Select which schemas/tables to include
5. Optionally rename schemas (e.g., `dbo` → `app_schema`)
6. Review the generated SQL
7. Click **Run SQL** to apply to target

<Tip>
  You can edit the generated SQL before applying it if you need to make adjustments for the target database.
</Tip>

### Step 2: Data Migration

Load data from source to target:

1. Click **Data** tab
2. Configure migration options:

<ResponseField name="extractionThreads" type="number" default="4">
  Number of parallel threads for extracting data from source.
</ResponseField>

<ResponseField name="loadingThreads" type="number" default="4">
  Number of parallel threads for loading data to target.
</ResponseField>

<ResponseField name="rowsPerFile" type="number" default="10000">
  Maximum rows per data file. Smaller values use less memory. When running data+replication mode, the default is 50,000.
</ResponseField>

3. Click **Start Data Migration**
4. Monitor progress in real-time via the graph

### Step 3: Data Validation

Verify data integrity after migration:

1. Click **Validate** tab
2. Set sample percentage (1-100%)
3. Click **Run Validation**
4. Review per-table results showing row count comparisons

### Step 4: Replication (Optional)

Enable Change Data Capture (CDC) for continuous replication:

1. Click **Replication** tab
2. Configure replication threads
3. Click **Start Replication**
4. Monitor change lag in real-time

<Note>
  Replication keeps your target synchronized with ongoing changes to the source database.
</Note>

#### Replication Controls

* **Pause** - Temporarily stop applying changes (source still tracks changes)
* **Resume** - Continue applying queued changes
* **Stop** - Permanently stop replication

## Real-Time Progress Monitoring

The GUI provides real-time graphs showing:

* **Extracted Rows** - Data pulled from source (blue line)
* **Loaded Rows** - Data written to target (green line)
* **Per-Table Progress** - Breakdown by individual tables

Graphs update automatically every 2 seconds during active migrations.

## Tools

### Wiretalk Query Executor

Execute ad-hoc SQL queries against your sources or targets:

1. Click **Tools** → **Wiretalk**
2. Select source or target connection
3. Enter your SQL query
4. Click **Execute**
5. View results in tabular or vertical format

### Log Downloads

Download migration logs for troubleshooting:

1. Open your migration
2. Click **Download Logs**
3. Receive a ZIP file containing all log files

## Scheduling

Set up automated data refreshes:

1. Open your migration
2. Click **Schedule** tab
3. Select frequency:
   * Hourly
   * Every 6 hours
   * Every 12 hours
   * Daily (select time)
   * Weekly (select day and time)
   * Custom (cron expression)
4. Click **Save Schedule**

## User Management

Root users can manage other users:

1. Click your username → **User Management**
2. **Add User** - Create new accounts
3. **Delete User** - Remove accounts

<Note>
  Regular users can only see and manage their own migrations. Root users can see all migrations.
</Note>

## Configuration

### Server Configuration File

The UX Server reads configuration from `ux-server.cfg`:

```ini theme={null}
# Server port (default 8443)
PORT=8443

# SSL certificates
CERT_FILE=/opt/wirekite/ux/server/certs/server.crt
KEY_FILE=/opt/wirekite/ux/server/certs/server.key

# Directory paths
STATIC_DIR=/opt/wirekite/ux/static
CONFIG_DIR=/opt/wirekite/ux/configs
ORCHESTRATOR_BIN=/opt/wirekite/orchestrator/wirekite

# Optional: IP whitelist (comma-separated)
ALLOWED_IPS=192.168.1.100,192.168.1.101
```

### SSL Certificates

Generate self-signed certificates for testing:

```bash theme={null}
openssl req -x509 -newkey rsa:4096 \
  -keyout /opt/wirekite/ux/server/certs/server.key \
  -out /opt/wirekite/ux/server/certs/server.crt \
  -days 365 -nodes -subj "/CN=your-hostname"
```

For production, use certificates from a trusted CA or Let's Encrypt.

## Systemd Service

### Service File

Create `/etc/systemd/system/wirekite-ux.service`:

```ini theme={null}
[Unit]
Description=Wirekite UX Server
After=network.target

[Service]
Type=simple
User=wirekite
Group=wirekite
WorkingDirectory=/opt/wirekite/ux/server
ExecStart=/opt/wirekite/ux/server/ux-server
Restart=always
RestartSec=10
StandardOutput=append:/opt/wirekite/ux/logs/ux-server.log
StandardError=append:/opt/wirekite/ux/logs/ux-server-error.log
Environment="GIN_MODE=release"

[Install]
WantedBy=multi-user.target
```

### Service Commands

```bash theme={null}
# Enable on boot
sudo systemctl enable wirekite-ux

# Start service
sudo systemctl start wirekite-ux

# Check status
sudo systemctl status wirekite-ux

# View logs
sudo journalctl -u wirekite-ux -f

# Restart after config changes
sudo systemctl restart wirekite-ux
```

## Directory Structure

```
/opt/wirekite/
├── orchestrator/wirekite           # Main orchestrator binary
├── ux/
│   ├── server/
│   │   ├── ux-server               # UX server binary
│   │   ├── ux-server.cfg           # Configuration
│   │   └── certs/                  # SSL certificates
│   ├── static/                     # Web assets (HTML/CSS/JS)
│   └── logs/                       # Server logs
├── instance/                       # Migration data
│   ├── migrations.json             # Migration registry
│   ├── sources/                    # Source DSN files
│   ├── targets/                    # Target DSN files
│   └── <migration-name>/           # Per-migration data
│       ├── schema/
│       ├── data/
│       ├── change/
│       └── logs/
└── wiretalk/wiretalk               # Query tool
```

## Troubleshooting

### Cannot Connect to UX Server

1. Verify the service is running: `systemctl status wirekite-ux`
2. Check the server logs: `tail -f /opt/wirekite/ux/logs/ux-server.log`
3. Ensure port 8443 is open in your firewall
4. Verify SSL certificates exist and are readable

### Migration Stuck or Failed

1. Check the migration logs via **Download Logs**
2. Review `orchestrator.log` for high-level errors
3. Check extractor/loader logs for specific issues
4. Verify source/target connectivity with **Test Connection**

### Authentication Issues

1. Clear browser cookies and try logging in again
2. Check `sessions.json` hasn't become corrupted
3. Verify `users.json` contains your user account
4. Restart the UX server to clear all sessions