Initial commit

GITLAB_DEPLOYMENT.md

@@ -0,0 +1,167 @@
+# 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