mude Setup

`mude` Setup#

To modify the server setup, SSH into mude.citg.tudelft.nl. You can use the command below:

sudo nano /var/web_server/website_docker_configuration/default.conf

location /archive {
        alias /var/www/html/archive;
        index index.html index.htm intro.html;
        try_files $uri $uri/ =404;
}
location /incoming {
        alias /var/www/html/incoming;
        index index.html index.htm intro.html;
        try_files $uri $uri/ =404;
}
location /teacher {
        alias /var/www/html/teacher;
        index index.html index.htm inro.html;
        try_files $uri $uri/ =404;
}

This is the example of the subdomain:

All you need to do to set up the new subdomain is to write exactly as the example shows.

Configuration Details#

Alias#

alias /var/www/html/{domain name};

This sets the alias for the / {domain name} location to the directory /var/www/html/{domain name}. When a request matches / {domain name}, Nginx serves the files from this directory.

If you cd /var/www/html, you could see nothing except the default Nginx index.html file on the mude.citg.tudelft.nl Linux server. This is because the server is using a proxy. /var/web_server/htdocs/ is where the actual contents stay.

Index Files#

index index.html index.htm intro.html;

This specifies the default files to serve if a directory is requested. Nginx will look for index.html, index.htm, or intro.html in that order.

To add a new subdomain and index.html for the new website, use the command:

cd /var/web_server/htdocs/
sudo mkdir {domain name}
sudo nano {domain name}/index.html

Write down anything in the index.html file. Press (Ctrl+X -> Y) to save and exit from the nano text editor. In this way, your index.html file will be created successfully.

Try Files#

try_files $uri $uri/ =404;

This directive attempts to serve the requested URI as a file or a directory. If neither exists, it returns a 404 error.

Restarting Docker#

After you finish the setup above, you need to restart the Docker container with the following commands:

Check if the configuration is correct:

sudo docker exec website_docker_configuration-nginx-1 nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If it shows this, then it is well done.

If the test is successful, reload Nginx:

sudo docker exec website_docker_configuration-nginx-1 nginx -s reload

[notice] 36#36: signal process started

This message means the server is successfully reloaded.

Now you can navigate to mude.citg.tudelft.nl/{domain name} to test your new website!

Webhook Deployment#

Instead of using direct SSH access for deploying files, GitLab provides a service called “Webhook.” This allows us to automatically deploy files from the GitLab repository and execute bash scripts on the webserver to build and update the website.

For instance, a webhook configuration file can be found at /etc/webhook/hooks.json. Below is an example of such a configuration:

  {
    "id": "book-deploy-draft",
    "execute-command": "/srv/webhook/deploy_book_artifact.sh",
    "pass-arguments-to-command": [
      {
        "source": "payload",
        "name": "object_attributes.ref"
      },
      {
        "source": "string",
        "name": "book/_build/html"
      },
      {
        "source": "string",
        "name": "/var/web_server/htdocs/2024/book-draft"
      },
      {
        "source": "string",
        "name": "ACCESS TOKEN"
      },
      {
        "source": "payload",
        "name": "build_job_id"
      },
      {
        "source": "string",
        "name": "mude/book"
      }
    ],
    "trigger-rule": {
      "and": [
        {
          "match": {
            "type": "value",
            "value": "pipeline",
            "parameter": {
              "source": "payload",
              "name": "object_kind"
            }
          }
        },
        {
          "match": {
            "type": "value",
            "value": "success",
            "parameter": {
              "source": "payload",
              "name": "object_attributes.status"
            }
          }
        },
        {
          "match": {
            "type": "value",
            "value": "main",
            "parameter": {
              "source": "payload",
              "name": "object_attributes.ref"
            }
          }
        },
        {
          "match": {
            "type": "value",
            "value": "ACCESS TOKEN",
            "parameter": {
              "source": "header",
              "name": "X-Gitlab-Token"
            }
          }
        }
      ]
    },
    "trigger-rule-mismatch-http-response-code": 200
  }

This configuration defines a webhook event, book-deploy-draft, which triggers the execution of a shell script (/srv/webhook/deploy_book_artifact.sh) when a webhook is received from GitLab.

Key Points:#

The placeholder “ACCESS TOKEN” should be replaced with the actual token you create (instructions on creating the token are provided below).
This webhook is triggered when a pipeline on the main branch successfully completes. It deploys the book draft from the directory book/_build/html to /var/web_server/htdocs/2024/book-draft.
The webhook service can be configured in GitLab -> Settings -> Webhooks.

Setting Up the Webhook#

To set up the webhook service, follow these steps:

Create a Personal Access Token Navigate to GitLab -> Settings -> Access Tokens and create a new token. The scopes and role should match the following example, while other details (like name and expiration date) can be customized.

Token Name	Scopes	Created	Last Used	Expires	Role
Automatic deployment	read_api, read_repository	Aug 30, 2024	11 hours ago	in 11 months	Developer

Set Up the Webhook Go to GitLab -> Settings -> Webhooks and add a new webhook with the following settings:

URL: Enter the URL of your webhook, for example: https://mude.citg.tudelft.nl/hooks/book-deploy-draft (this should match the URL in your webhook configuration file).
Secret Token: Paste the access token you created earlier into the “Secret Token” field.
Trigger: Enable Pipeline events.
SSL Verification: Ensure that SSL verification is enabled.
Finally, click Add Webhook.

With these steps completed, your webhook will automatically trigger the deployment process whenever a successful pipeline runs on the main branch.

`interactivetextbooks` setup#

This has a GitLab CI/CD pipeline configuration file that automates the process of building a Docker image, pushing it to a Docker registry, and deploying it in a containerized environment. Here’s a breakdown of the stages and commands:

Stages#

build: This stage handles the creation and pushing of a Docker image.
deploy: This stage handles deploying the built Docker image to a running container.

Variables#

REGISTRY_HOST: Set to localhost:5000, representing the local Docker registry.
TAG: This variable constructs a Docker image tag using the registry host, project name, and the branch name. The format is localhost:5000/project_name/branch_name:latest.

Build Stage#

Image: The pipeline uses the official Docker image to execute Docker commands.
Rules: The pipeline will only run this stage if the branch is main and the pipeline was triggered by a push event.
Before script: Runs docker info to confirm that Docker is working correctly.
Script:
- docker build -t $TAG .: This builds a Docker image with the specified tag ($TAG) using the current directory as the build context.
- docker push $TAG: Pushes the built Docker image to the local registry (localhost:5000).

Deploy Stage#

Image: Uses the Docker image again to handle container management.
Rules: This stage also runs only if the branch is main and the pipeline was triggered by a push event.
Before script:
- docker info: Same as the build stage, checks Docker’s status.
- docker stop $CI_PROJECT_NAME: Attempts to stop any running container with the project name as the container name.
- if [ $exit_code -ne 0 ]; then echo "Container not found, cannot stop"; else docker rm $CI_PROJECT_NAME; fi: If stopping the container fails (i.e., the container doesn’t exist), a message is printed, but it continues execution. If successful, the container is removed.
Script:
- docker run -d --restart always -p 8007:80 --name $CI_PROJECT_NAME $TAG: This runs the newly built and pushed Docker image as a container. The container is set to always restart, runs detached (-d), and exposes port 8007 on the host, forwarding it to port 80 in the container.

Summary#

The pipeline is triggered on pushes to the main branch.
In the build stage, it builds a Docker image and pushes it to a local Docker registry at localhost:5000.
In the deploy stage, it stops and removes any existing container, then runs a new container with the built image, exposing port 8007 on the host machine.

`SSL Certificate Setup` Guide#

Before You Begin#

Authentication: Use your NetID login credentials for all server access.
File Handling: Commands assume copying, pasting, or transferring files to the current working directory.

Generating CSR (Certificate Signing Request) on Webserver#

Create CSR File on Webserver:
- Follow this guide to generate .csr and .key files on your webserver.

Transferring CSR from Server to Local Machine#

Secure Copy (SCP) from Server to Local:

Access the intermediary server:

ssh {NetID}@student-linux.tudelft.nl or {NetID}@linux-bastion.tudelft.nl

Copy the .csr file from server to intermediary server:

scp mude.citg.tudelft.nl:mude.citg.tudelft.nl.csr /home/nfs/{NetId}/

Copy the .csr file from intermediary server to your local machine:

scp {NetID}@student-linux.tudelft.nl:/home/nfs/{NetID}/mude.citg.tudelft.nl.csr .

Requesting SSL Certificate#

Submit CSR to TUDelft Top Desk:
- Visit TUDelft Top Desk and submit the .csr file to request your SSL certificate.

Uploading PEM File to Webserver#

To figure out where the current cerficate exists, use the command below:

sudo nano /etc/nginx/sites-available/mude

server {
    # SSL configuration
    #
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    ssl_certificate /etc/ssl/certs/mude_citg_tudelft_nl.pem;
    ssl_certificate_key /etc/ssl/private/mude.citg.tudelft.nl.key;

In this example, ssl_certificate and key are staying in (This key file should be created with the .csr)

/etc/ssl/certs
/etc/ssl/private

SCP from Local Machine to Intermediary Server:

Upload .pem file to intermediary server:

scp mude.citg.tudelft.nl.pem {NetID}@student-linux.tudelft.nl:/home/nfs/{NetID}/

SCP from Intermediary Server to Webserver:

Access intermediary server:
```
ssh {NetID}@student-linux.tudelft.nl
```

Transfer .pem file to webserver:

scp /home/nfs/{NetID}/mude.citg.tudelft.nl.pem {NetID}@mude.citg.tudelft.nl:

Updating SSL Certificate#

Backup existing SSL files:

sudo cp /etc/ssl/certs/mude_citg_tudelft_nl.pem /etc/ssl/certs/mude_citg_tudelft_nl.pem.bak
sudo cp /etc/ssl/private/mude.citg.tudelft.nl.key /etc/ssl/private/mude.citg.tudelft.nl.key.bak

Replace with new .pem and .key files:

sudo cp /path/to/new/mude.citg.tudelft.nl.pem /etc/ssl/certs/mude_citg_tudelft_nl.pem
sudo cp /path/to/new/mude.citg.tudelft.nl.key /etc/ssl/private/mude.citg.tudelft.nl.key

Set permissions:

sudo chmod 777 /etc/ssl/certs/mude_citg_tudelft_nl.pem
sudo chmod 600 /etc/ssl/private/mude.citg.tudelft.nl.key
sudo chown root:root /etc/ssl/certs/mude_citg_tudelft_nl.pem
sudo chown root:root /etc/ssl/private/mude.citg.tudelft.nl.key

Update nginx configuration:
```
sudo nano /etc/nginx/sites-available/mude
```
Update ssl_certificate and ssl_certificate_key paths to point to new files. (It will be the same if you follow the instructions)

Verify and restart nginx:

sudo nginx -t
sudo systemctl restart nginx

Creating New Password for authentication#

This process involves a few steps to update your .htpasswd file. Here’s a streamlined guide to help you (there should be better way but this is the only way that I can figure out at this moment, please update this if you find something better!)

Create a new password (Delete this file after everything is done.) Use the following command to generate a new password:

sudo htpasswd -c /etc/nginx/.htpasswd teacher
#Teacher is the username here.

Retrieve the New Password
View the updated .htpasswd file to copy the new password format:

sudo cat /etc/nginx/.htpasswd
#The format would be this: teacher:$apr1$1ktW7oqwewveq45123dsd
#Teacher is the username and the other is MD5-based Apache crypt (denoted by $apr1$)

Access the Nginx Docker Container

sudo docker exec -it website_docker_configuration-nginx-1 /bin/sh
#Replace website_docker_configuration-nginx-1 with your Docker container name if different.

Create and Edit the Password File
Inside the container, navigate to /etc/nginx and create a new file:

cd /etc/nginx
touch $anyname #this name is flexible
vi $anyname
#Press i to enter insert mode
#Paste the copied password format teacher:$apr1$1ktW7oqwewveq45123dsd
#Press Esc to exit insert mode
#Type :wq and press Enter to save and quit

Create the Configuration File
Still inside the container, navigate to /etc/nginx/snippets and create a new .conf file:

cd /etc/nginx/snippets
touch $anyname.conf #this name is flexible
vi $anyname.conf

#Press i to enter insert mode
#Write down folloiwng codes
auth_basic "You shall not pass";
auth_basic_user_file /etc/nginx/$anyname; #this is from step 4
#Press Esc to exit insert mode
#Type :wq and press Enter to save and quit

Reload Nginx Configuration

Exit the Docker container:

exit

Then reload the Nginx configuration to apply changes:

sudo docker exec website_docker_configuration-nginx-1 nginx -s reload