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:

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):

   ssh-keygen -t ed25519 -C "gitlab-deploy" -f gitlab-deploy-key
   

2. Add the public key to your server's authorized_keys:

   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

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:

# 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:

./build-test.sh [port]

Example:

./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:

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

Example:

./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