builder-prototype/GITLAB_DEPLOYMENT.md

# Deploying from a Self-Hosted GitLab Server

This guide provides detailed instructions for deploying the Dispute Protocol application from a self-hosted GitLab server.

## Prerequisites

- A self-hosted GitLab server (GitLab Community Edition or Enterprise Edition)
- GitLab Runner installed and configured on your server
- Basic familiarity with GitLab CI/CD

## Deployment Options

The project includes a `.gitlab-ci.yml` file that supports two deployment methods:

1. **GitLab Pages** - For hosting directly on your GitLab instance
2. **Custom Server Deployment** - For deploying to an external web server

## Option 1: Deploying to GitLab Pages

GitLab Pages provides an easy way to host static websites directly from your GitLab repository.

### Configuration Steps:

1. Ensure GitLab Pages is enabled on your self-hosted GitLab instance:
   - Go to Admin Area > Settings > Pages
   - Enable GitLab Pages and configure the domain settings

2. The existing `.gitlab-ci.yml` file already includes the necessary configuration for GitLab Pages. When you push to the `master` branch, the site will be automatically built and deployed.

3. Access your site at `https://[group-or-username].gitlab-instance.com/dispute-protocol`

## Option 2: Deploying to a Custom Web Server

For more control, you can deploy to your own web server using rsync over SSH.

### Configuration Steps:

1. In your GitLab repository, go to **Settings > CI/CD > Variables**

2. Add the following variables:
   - `SSH_PRIVATE_KEY`: The private SSH key for connecting to your deployment server
   - `SSH_KNOWN_HOSTS`: Output of `ssh-keyscan your-server.com`
   - `SSH_USER`: Username on your deployment server
   - `SSH_HOST`: Hostname or IP address of your deployment server
   - `DEPLOY_PATH`: Path on your server where the site should be deployed

3. Edit the `.gitlab-ci.yml` file and uncomment the `deploy` job

4. Update the `url` parameter in the environment section with your actual domain

5. Push your changes to the `master` branch to trigger the deployment

### How to generate SSH_KNOWN_HOSTS value:

```bash
ssh-keyscan -H your-server.com
```

### How to generate and configure SSH keys:

1. Generate a new SSH key pair (without a passphrase for automated use):
   ```bash
   ssh-keygen -t ed25519 -C "gitlab-deploy" -f gitlab-deploy-key
   ```

2. Add the public key to your server's authorized_keys:
   ```bash
   cat gitlab-deploy-key.pub >> ~/.ssh/authorized_keys
   ```

3. Copy the private key content (including BEGIN and END lines) and paste it into the `SSH_PRIVATE_KEY` variable in GitLab

## Web Server Configuration

### Nginx Configuration

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    root /path/to/deployment;
    index index.html;
    
    location / {
        try_files $uri $uri/ =404;
    }
    
    # Optional: Enable gzip compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
}
```

### Apache Configuration

Create a .htaccess file in your deployment directory:

```apache
# Enable rewriting
RewriteEngine On

# If the requested resource doesn't exist as a file or directory
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# Rewrite to index.html
RewriteRule ^(.*)$ /index.html [L]

# Cache control for static assets
<FilesMatch "\.(css|js|png|jpg|jpeg|gif|ico)$">
    Header set Cache-Control "max-age=604800, public"
</FilesMatch>
```

## Manual Deployment

If you prefer to deploy manually without GitLab CI/CD, you can use the included scripts:

### Testing the Build Locally

Before deploying, you can test the build locally using the included `build-test.sh` script:

```bash
./build-test.sh [port]
```

Example:
```bash
./build-test.sh 8080
```

This will build the site and start a temporary web server on the specified port (default: 8080), allowing you to verify that everything works correctly before deployment.

### Deploying to a Remote Server

To deploy to your own server manually, use the included `deploy.sh` script:

```bash
./deploy.sh [username] [server] [deploy-path]
```

Example:
```bash
./deploy.sh deploy-user example.com /var/www/dispute-protocol
```

This script will build the site and then use rsync to deploy it to your server.

## Troubleshooting

### CI/CD Pipeline Fails

1. Check the pipeline logs for detailed error messages
2. Verify that the GitLab Runner is properly configured and running
3. Ensure the SSH key has the correct permissions on the target server
4. Try running the build and deploy steps manually to identify issues

### Site Not Accessible After Deployment

1. Check web server logs for errors
2. Verify file permissions in the deployment directory
3. Ensure the web server configuration is correct
4. Check that the domain DNS is pointing to the correct server