MkDocs configuration and content for info/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

5.9 KiB

Anthonyresearch

Basic Info

History

Installation

Atlas

See Atlas

Bouncer

Basic Info

History

Installation

CJSD

Basic Info

History

Installation

Crow

Basic Info

History

Installation

Docker [Inactive]

Basic Info

History

Installation

Docs

Basic Info

History

Installation

Dubsdot

Basic Info

History

Installation

Eldoom

Basic Info

History

Installation

Gitea

Basic Info

History

Installation

GMy [Inactive]

Basic Info

History

Installation

Info

The VM that is hosting this site!

info/ itself uses MkDocs to convert Markdown via the Python-Markdown library with various extensions into webcontent. MkDocs includes the ability to host the content it creates, but it is better to point an actual webserver at the content instead. nginx was chosen for this task, and a SSL certificate was obtained from Let's Encrypt via Certbot. info/ is accesible from both HTTP and HTTPS as configured.

Currently, info/ is using the Cinder theme.

Basic Info:

  • Host: Hydra
  • Maintainer: Cameron
  • Cores: 1
  • RAM: 1G
  • Disk: 20 GB
  • OS: Arch Linux
  • IP: 128.153.145.101
  • Technologies: nginx, certbot, mkdocs, sshd

History

The previous documentation webservice used to be the place to record documentation and other info about the labs. However, due to the MediaWiki instance becoming unstable and problematic to maintain, a Gitea instance was created to replace it. Rather than being a wiki, it was a Git server being used as a way to version control documentation and configuration. info/ was created to act as a prettier front-end to the lab's record keeping.

Installation

Create a lightweight VM on a capable VM Host and provide it enough resources to run a web server. A single core and 20 GB of disk should suffice. Perform a basic Arch Linux install and install the following additional packages

nginx certbot certbot-nginx python3 python-pip

MkDocs isn't strictly required to be installed on the VM in order for it to work, but it is handy to have it installed. Install the following packages via pip3:

mkdocs mkdocs-cinder

Nginx and Certbot

To make info/ an HTTPS server, we need a SSL certificate. Grab one by running:

sudo certbot certonly --nginx -d info.cosi.clarkson.edu -d info.cslabs.clarkson.edu

You may need to run it a few times until all the keys are obtained. Ensure the fullchain.pem and privkey.pem files are installed at /etc/letsencrypt/live/info.cosi.clarkson.edu/ and /etc/letsencrypt/live/info.cslabs.clarkson.edu/.

Copy the following config into /etc/nginx/nginx.conf:

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;

    ssl_protocols TLSv1.2 TLSv1.3;
    server {
	listen	80 default_server;
	listen	[::]:80 default_server;
        listen	443 ssl http2 default_server;
        listen	[::]:443 ssl http2 default_server;
        server_name  _;

        ssl_certificate      /etc/letsencrypt/live/info.cosi.clarkson.edu/fullchain.pem;
        ssl_certificate_key  /etc/letsencrypt/live/info.cosi.clarkson.edu/privkey.pem;

        ssl_session_cache    shared:SSL:1m;
        ssl_session_timeout  5m;

        ssl_ciphers  HIGH:!aNULL:!MD5;
        ssl_prefer_server_ciphers  on;

        location / {
            root   /usr/share/nginx/html/info-slash;
            index  index.html index.htm;
        }
    }
}

Change the root field under location to just /usr/share/nginx/html since we haven't installed the webcontent yet. Enable and start the nginx systemd service, aptly named "nginx.service". Now would be a good time to configure the firewall to allow traffic on port 80 and 443. Verify that the default nginx webpage is accessible before changing the root field back.

Syncing with Gitea with Systemd

Our Gitea instance houses and version controls both the source and the web content. In the /usr/share/nginx/html directory, run git clone https://gitea.cslabs.clarkson.edu/COSI_Sysadmins/info-slash.git -b gh-pages. Restart the nginx service and info/ should be available.

Finally, a systemd service and timer needs to be created to handle updating the website periodically. Create the mkdocs-pull.service file in /etc/systemd/system/ directory and copy the following into it:

[Unit]
Description=Pulls down most recent changes from Gitea for the MkDocs instance

[Service]
Type=simple
WorkingDirectory=/usr/share/nginx/html/info-slash/
ExecStart=/usr/bin/git pull

Create the mkdocs-pull.timer service next to it and copy the following into it:

Description=Pull down changes for MkDocs periodically

[Timer]
OnActiveSec=1s
OnUnitActiveSec=5m

[Install]
WantedBy=timers.target

Finally, enable and start the timer and verify that the service is running periodically. Run systemctl list-timers to help debug the timer and journalctl -xe for debug logs.

Library

Basic Info

History

Installation

Linalg [Inactive]

Basic Info

History

Installation

Mail [Inactive]

Basic Info

History

Installation

Nagios [Inactive]

Basic Info

History

Installation

OpenVPN

Basic Info

History

Installation

QVM

Basic Info

History

Installation

ROS-PXE [Inactive]

Basic Info

History

Installation

Scan2 [Inactive]

Basic Info

History

Installation

SDR Server [Inactive]

Basic Info

History

Installation

Seance-PXE

Basic Info

History

Installation

Tino

Basic Info

History

Installation

Undocs

Basic Info

History

Installation

Undocs2 [Inactive]

Basic Info

History

Installation

Unify Controller

Basic Info

History

Installation

VOIP

See VOIP