CSCWiki - User contributions [en]

CloudStack

2025-07-01T19:55:27Z

K57chan:

We are using [https://cloudstack.apache.org/ Apache CloudStack] to provide VMs-as-a-service to members. Our user documentation is here: https://docs.cloud.csclub.uwaterloo.ca

Prerequisite reading:

* [[Ceph]]
* [[Cloud Networking]]

Official CloudStack documentation: http://docs.cloudstack.apache.org/en/4.16.0.0/

== Rebooting machines ==
I'm going to start with this first because this is what future sysadmins are most interested in. If you reboot one of the CloudStack guest machines (as of this writing: biloba, ginkgo and chamomile), then I suggest you perform a live migration of all of the VMs on that host to the other other machines (see [[#Sequential reboot]]).

If this is not possible (e.g. there is not enough capacity on the other machines), then CloudStack will most likely shut down the VMs automatically. You are responsible for restarting them manually after the reboot. You will also need to manually restart any Kubernetes clusters.

Note: if the cloudstack-agent.service is having trouble reconnecting to the management servers after a reboot, just do a systemctl restart and cross your fingers.

=== Sequential reboot ===
If it is possible to reboot the machines one at a time (e.g. for a software upgrade), then it is possible to avoid having any downtime. Login to the web UI as admin, go to Infrastructure > Hosts, hover above the three-dots button for a particular host, then press the "Enable Maintenance Mode" button.
[[File:Cloudstack-enable-maintenance-mode-button.png|1000px]]
 
Wait for the VMs to be migrated to the other machines (press the Refresh button to update the table). If you see an error which says "ErrorInPrepareForMaintenance", just wait it out. If more than 20 minutes have passed and there is still no progress, take the host out of maintenance mode, and put it back into maintenance mode. If this still does not work, restart the management server.

When a host is in maintenance mode, it should look like this:
[[File:Cloudstack-host-in-maintenance-mode.png|1000px]]
 
Once all VMs have been migrated, do whatever you need to do on the physical host; once it is back up, take it back out of maintenance mode from the web UI. Repeat for any other hosts which need to be taken offline.

== Unexpected reboot ==
Sometimes a network interface fails on a machine after the switches in MC are rebooted (looking at you, riboflavin). Or a machine randomly goes offline in the middle of the night (looking at you, ginkgo). Point is, sometimes a machine needs to rebooted, or is forcefully rebooted, without preparation. Unfortunately, CloudStack is unable to recover gracefully from an unexpected reboot. This means that manual intervention is required to get the VMs back into a working state.

Once the machine has come back online, perform the following:
<ol>
<li>All of the VMs which were on that machine will eventually transition to the Stopped state. Wait for this to happen first (from the web UI).</li>
<li>Go to Infrastructure -> Management servers and make sure that both biloba and chamomile are present and running. If not, you may need to restart the management server on the machine (<code>systemctl restart cloudstack-management</code>). Watch the journald logs for any error messages.</li>
<li>Go to Infrastructure -> Hosts and make sure that all three hosts (biloba, chamomile and ginkgo) are present and running. If not, you may need to restart the agent on the machine (<code>systemctl restart cloudstack-agent</code>). Watch the journald logs for any error messages.</li>
<li>If you restart cloudstack-agent, restart virtlogd as well, just for good measure. Watch the journald logs for any error messages.</li>
<li>Restart ONE of the stopped VMs and make sure that it transitions to the Started state. If more than 20 minutes pass and it still hasn't started, restart the management servers and try again.</li>
<li>Restart the rest of the stopped VMs.</li>
</ol>

== Administration ==
To login with the admin account, use the following credentials in the web UI
<ul>
<li>Username: admin</li>
<li>Password: stored in the usual place</li>
<li>Domain: leave this empty</li>
</ul>

There is another admin account for the Members domain. This is necessary to create projects in the Members domain which regular members can access. Note that his account has fewer privileges than the root admin account above (it has the DomainAdmin role instead of the RootAdmin role).
<ul>
<li>Username: membersadmin</li>
<li>Password: stored in the usual place</li>
<li>Domain: Members
</ul>

Note that there are two management servers, one on each of biloba and chamomile (chamomile is a hot standby for biloba). If you restart one of them, you should restart the other as well.

=== CLI ===
CloudStack has a CLI called [https://github.com/apache/cloudstack-cloudmonkey cloudmonkey] which is already set up on biloba. Just run <code>cmk</code> as root to start it up.

Cloudmonkey is basically a shell for the API (https://cloudstack.apache.org/api/apidocs-4.16/). For example, to list all domains:
<pre>
listDomains details=min
</pre>
Run <code>somecommand -h</code> to see all parameters for a particular command (or browse the API documentation).
See https://github.com/apache/cloudstack-cloudmonkey for more details.

== Building packages ==
While CloudStack does provide .deb packages for Ubuntu, unfortunately these don't work on Debian (the 'qemu-kvm' dependency is a virtual package on Debian, but not on Ubuntu). So we're going to build our own packages instead.

We're going to perform the build in a Podman container to avoid polluting the host machine with unnecessary packages. There's a container called cloudstack-build on biloba which you can re-use. If you create a new container, make sure to use the same Podman image as the release for which you're building (e.g. 'debian:bullseye').

The instructions below are adapted from http://docs.cloudstack.apache.org/en/latest/installguide/building_from_source.html

Inside the container, install the dependencies:
<pre>
apt install maven openjdk-11-jdk libws-commons-util-java libcommons-codec-java libcommons-httpclient-java liblog4j1.2-java genisoimage devscripts debhelper python3-setuptools
</pre>
Install Node.js 12 as well (Debian bullseye's version happens to be 12):
<pre>
apt install nodejs npm
</pre>
Build the node-sass module (see [https://github.com/sass/node-sass/issues/1579 this issue] to see why this is necessary):
<pre>
cd ui && npm install && npm rebuild node-sass && cd ..
</pre>
The python3-mysql.connector package is not available in bullseye, so we're going to download and install it from the sid release:
<pre>
curl -LOJ http://ftp.ca.debian.org/debian/pool/main/m/mysql-connector-python/python3-mysql.connector_8.0.15-2_all.deb
apt install ./python3-mysql.connector_8.0.15-2_all.deb
</pre>
Download the CloudStack source code:
<pre>
curl -LOJ http://mirror.csclub.uwaterloo.ca/apache/cloudstack/releases/4.16.0.0/apache-cloudstack-4.16.0.0-src.tar.bz2
tar -jxvf apache-cloudstack-4.16.0.0-src.tar.bz2
cd apache-cloudstack-4.16.0.0-src
</pre>
Download the Maven dependencies:
<pre>
mvn -P deps
</pre>
Now open debian/control and perform the following changes:

* Replace 'qemu-kvm (>=2.5)' with 'qemu-system-x86 (>= 1:5.2)' in the dependencies of cloudstack-agent
* Remove dh-systemd as a build dependency of cloudstack (it's included in debhelper)

Now open debian/rules and add the following flags to the <code>mvn</code> command:
<pre>
-Dmaven.test.skip=true -Dclean.skip=true -Dcheckstyle.skip
</pre>

Now open debian/changelog and change 'unstable' to 'bullseye'.

As of this writing, there is a [https://gitlab.com/libvirt/libvirt/-/issues/161 bug in libvirt] which prevents VMs with more than 4GB of RAM from being created on hosts with cgroups2. Until that issue is fixed, we're going to need to modify the source code. Since we're already building a custom CloudStack package, it's easier to patch CloudStack than to patch libvirt, so paste something like the following into debian/patches/fix-cgroups2-cpu-weight.patch:
<pre>
Description: Workaround for libvirt trying to write a value to the cgroups v2
cpu.weight controller which is greater than the maximum (10000). The
libvirt developers are currently discussing a solution.
Forwarded: not-needed
Origin: upstream, https://gitlab.com/libvirt/libvirt/-/issues/161
Author: Max Erenberg <merenber@csclub.uwaterloo.ca>
Last-Update: 2021-12-03
Index: apache-cloudstack-4.16.0.0-src/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtVMDef.java
===================================================================
--- apache-cloudstack-4.16.0.0-src.orig/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtVMDef.java
+++ apache-cloudstack-4.16.0.0-src/plugins/hypervisors/kvm/src/main/java/com/cloud/hypervisor/kvm/resource/LibvirtVMDef.java
@@ -1483,6 +1483,10 @@ public class LibvirtVMDef {
static final int MAX_PERIOD = 1000000;

public void setShares(int shares) {
+ // Clamp the value to the cgroups v2 cpu.weight maximum until
+ // upstream libvirt gets fixed:
+ // https://gitlab.com/libvirt/libvirt/-/issues/161
+ shares = Math.min(shares, 10000);
_shares = shares;
}
</pre>
I think you have to manually modify that LibvirtVMDef.java file to incorporate those changes (I could be wrong on this, but that's how I did it).

Then paste the following into debian/patches/00list:
<pre>
fix-cgroup2-cpu-weight
</pre>

Finally, import your GPG key into the container (make sure to delete it afterwards!), and build the packages:
<pre>
debuild -k<YOUR_GPG_KEY_ID>
</pre>

There should already be a .dupload.conf in the /root directory in the cloudstack-build container; if you need need another copy, ask a syscom member. Open /root/.ssh/config and change the User parameter to your username. Finally, go to /root and upload the packages to potassium-benzoate (replace the version number):
<pre>
dupload cloudstack_4.16.0.0+1_amd64.changes
</pre>

== Incompatibility with Debian 12 packages ==
After upgrading ginkgo to bookworm, we discovered that libvirt 8+ was incompatible with CloudStack 4.16.0.0. See https://www.shapeblue.com/advisory-on-libvirt-8-compatibility-issues-with-cloudstack/ for details. So we built new packages from the 4.16.1.0 branch of ShapeBlue's GitHub repository. For some reason the cloudstack-management process failed with some errors from SLF4J, so we needed to download some JARs:

<pre>
wget -O /usr/share/cloudstack-management/lib/log4j-1.2.17.jar https://repo1.maven.org/maven2/log4j/log4j/1.2.17/log4j-1.2.17.jar
wget -O /usr/share/cloudstack-management/lib/slf4j-log4j12-1.6.6.jar https://repo1.maven.org/maven2/org/slf4j/slf4j-log4j12/1.6.6/slf4j-log4j12-1.6.6.jar
</pre>

See https://stackoverflow.com/a/70528383 for details.

We also encountered some kind of Java 11 -> 17 incompatibility issue, so following parameters were added to the JAVA_OPTS variable in /etc/default/cloudstack-management:

<pre>
--add-opens java.base/java.lang=ALL-UNNAMED
</pre>

See https://stackoverflow.com/a/41265267 for details. Note that this file is NOT a shell script so you cannot use variable interpolation. You must modify the value of JAVA_OPTS directly.

== Database setup ==
We are using master-master replication between two MariaDB instances on biloba and chamomile. See [https://mariadb.com/kb/en/setting-up-replication/ here] and [https://tunnelix.com/simple-master-master-replication-on-mariadb/ here] for instructions on how to set this up.

To avoid split-brain syndrome, mariadb.cloud.csclub.uwaterloo.ca points to a virtual IP shared by biloba and chamomile via keepalived. This means that only one host is actually handling requests at any moment; the other is a hot standby.

Also add the following parameters to /etc/mysql/my.cnf on the hosts running MariaDB:
<pre>
[mysqld]
innodb_rollback_on_timeout=1
innodb_lock_wait_timeout=600
max_connections=350
log-bin=mysql-bin
binlog-format = 'ROW'
</pre>
Also comment out (or remove) the following line in /etc/mysql/mariadb.conf.d/50-server.cnf:
<pre>
bind-address = 127.0.0.1
</pre>
Now restart MariaDB.

== Management server setup ==
Install the management server from our Debian repository:
<pre>
apt install cloudstack-management
</pre>

Run the database scripts:
<pre>
cloudstack-setup-databases cloud:password@localhost --deploy-as=root
</pre>
(Replace 'password' by a strong password.)

Open /etc/cloudstack/management/db.properties and replace all instances of 'localhost' by 'mariadb.cloud.csclub.uwaterloo.ca'.

Open /etc/cloudstack/management/server.properties and set 'bind-interface' to 127.0.0.1 (CloudStack is being reverse proxied behind NGINX).

Run some more scripts:
<pre>
cloudstack-setup-management
</pre>

Mount the cloudstack-secondary CephFS volume at /mnt/cloudstack-secondary:
<pre>
mkdir /mnt/cloudstack-secondary
mount -t nfs4 -o port=2049 ceph-nfs.cloud.csclub.uwaterloo.ca:/cloudstack-secondary /mnt/cloudstack-secondary
</pre>
Now download the management VM template:
<pre>
/usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m /mnt/cloudstack-secondary/ -u https://download.cloudstack.org/systemvm/4.16/systemvmtemplate-4.16.0-kvm.qcow2.bz2 -h kvm -F
</pre>

The management server will run on port 8080 by default, so reverse proxy it from NGINX:
<pre>
location / {
proxy_pass http://localhost:8080;
}
</pre>

== Compute node setup ==
Install packages:
<pre>
apt install cloudstack-agent libvirt-daemon-driver-storage-rbd qemu-block-extra
</pre>
Create a new user for CloudStack:
<pre>
useradd -s /bin/bash -d /nonexistent -M cloudstack
# set the password
passwd cloudstack
</pre>
Add the following to /etc/sudoers:
<pre>
cloudstack ALL=(ALL) NOPASSWD:ALL
Defaults:cloudstack !requiretty
</pre>
(There is a way to restrict this, but I was never able to get it to work.)

=== Network setup ===
The /etc/network/interfaces file should look something like this (taking ginkgo as an example):
<pre>
auto enp3s0f0
iface enp3s0f0 inet manual

auto ens1f0np0
iface ens1f0np0 inet manual

# csc-cloud management
auto enp3s0f0.529
iface enp3s0f0.529 inet manual

auto br529
iface br529 inet static
bridge_ports enp3s0f0.529
address 172.19.168.22/27
iface br529 inet6 static
bridge_ports enp3s0f0.529
address fd74:6b6a:8eca:4902::22/64

# csc-cloud provider
auto ens1f0np0.425
iface ens1f0np0.425 inet manual

auto br425
iface br425 inet manual
bridge_ports ens1f0np0.425

# csc server network
auto ens1f0np0.134
iface ens1f0np0.134 inet manual

auto br134
iface br134 inet static
bridge_ports ens1f0np0.134
address 129.97.134.148/24
gateway 129.97.134.1
iface br134 inet6 static
bridge_ports ens1f0np0.134
address 2620:101:f000:4901:c5c::148/64
gateway 2620:101:f000:4901::1
</pre>
Add/modify the following lines to /etc/cloudstack/agent.properties:
<pre>
private.network.device=br529
guest.network.device=br425
public.network.device=br425
host=172.19.168.23,172.19.168.24@static
</pre>

=== libvirtd setup ===
Add/modify the following lines in /etc/libvirt/libvirtd.conf:
<pre>
listen_tls = 0
listen_tcp = 1
tcp_port = "16509"
auth_tcp = "none"
mdns_adv = 0
</pre>

Uncomment the following line in /etc/default/libvirtd:
<pre>
LIBVIRTD_ARGS="--listen"
</pre>

Make sure the following lines are present in /etc/libvirt/qemu.conf:
<pre>
security_driver="none"
user="root"
group="root"
</pre>

Now run:
<pre>
systemctl mask libvirtd.socket
systemctl mask libvirtd-ro.socket
systemctl mask libvirtd-admin.socket
systemctl restart libvirtd
</pre>

== Management server setup (cont'd) ==
Now start the cloudstack-management systemd service and visit the web UI (https://cloud.csclub.uwaterloo.ca). The login credentials are 'admin' for both the username and password. Start the setup walkthrough (you will be prompted to change the password). Make sure to choose Basic Networking.

The walkthrough is almost certainly going to fail (at least, it did for me). Don't panic when this happens; just abort the walkthrough, and set up everything else manually. Once primary and secondary storage have been setup, and at least one host has been added, enable the Pod, Cluster and Zone (there should only be one of each).

=== Primary Storage ===
* Type: RBD
* IP address: ceph-mon.cloud.csclub.uwaterloo.ca
* Scope: zone
* Get the credentials which you created in [[Ceph#CloudStack_Primary_Storage]]

=== Secondary Storage ===
* Type: NFS
* Host: ceph-nfs.cloud.csclub.uwaterloo.ca:2049
* Path: /cloudstack-secondary

=== Global settings ===
Some global settings which you'll need to set from the web UI:

* ca.plugin.root.auth.strictness: false (this always caused issues for me, so I just disabled it)
* host: 172.19.168.23,172.19.168.24 (the VLAN 529 addresses of biloba and chamomile)

=== Adding a host ===
This is an extremely painful process which I am almost certainly doing wrong. It usually takes me 7-8 attempts to add a single host (that's not an exaggeration). This is what it looks like:

* Stop cloudstack-agent service
* Configure /etc/cloudstack-agent/agent.properties
* Add a host from the CloudStack UI
* Start cloudstack-agent.service

The reason why this takes several attempts is because cloudstack-agent actually overwrites your agent.properties file. If/when you notice that this happens, restart the whole process again.

=== Accessing the System VMs ===
If you need to SSH into one of the System VMs, get its link-local address from the web UI, and run e.g.
<pre>
ssh -i /var/lib/cloudstack/management/.ssh/id_rsa -p 3922 root@169.254.232.179
</pre>

=== Some more global settings ===
<pre>
allow.user.expunge.recover.vm = true
allow.user.view.destroyed.vm = true
expunge.delay = 1
expunge.interval = 1
network.securitygroups.defaultadding = false
allow.public.user.templates = false
vm.network.throttling.rate = 0
network.throttling.rate = 0
cpu.overprovisioning.factor = 4.0
allow.user.create.projects = false
max.project.cpus = 8
max.project.memory = 8192
max.project.primary.storage = 40
max.projet.secondary.storage = 20
max.account.cpus = 8
max.account.memory = 8192
max.account.primary.storage = 40
max.account.secondary.storage = 20
</pre>

NOTE: the <code>cpu.overprovisioning.factor</code> setting also needs to be set for existing clusters. Go to Infrastructure -> Clusters -> Cluster1 -> Settings and set it accordingly.

=== Firewall ===
Since we disabled certificate validation from the clients, we're going to use some iptables-fu on all of the CloudStack hosts (to make our lives easier, we're going to use the same rules on the management and agent servers):
<pre>
iptables -N CLOUDSTACK-SERVICES
iptables -A INPUT -j CLOUDSTACK-SERVICES
iptables -A CLOUDSTACK-SERVICES -i lo -j RETURN
iptables -A CLOUDSTACK-SERVICES -s 172.19.168.0/27 -j RETURN
iptables -A CLOUDSTACK-SERVICES -p tcp -m multiport --dports 16509,16514,45335,41047,8250 -j REJECT
iptables-save > /etc/iptables/rules.v4

ip6tables -N CLOUDSTACK-SERVICES
ip6tables -A INPUT -j CLOUDSTACK-SERVICES
ip6tables -A CLOUDSTACK-SERVICES -i lo -j RETURN
ip6tables -A CLOUDSTACK-SERVICES -s fd74:6b6a:8eca:4902::/64 -j RETURN
ip6tables -A CLOUDSTACK-SERVICES -p tcp -m multiport --dports 16509,16514,45335,41047,8250 -j REJECT
ip6tables-save > /etc/iptables/rules.v6
</pre>

=== LDAP authentication ===
Go to Global Settings in the UI, type 'ldap' in the search bar, and configure the parameters as needed. Make sure the mail attribute is set to 'mailLocalAddress'.

Create a new domain called 'Members'. Then go to 'LDAP Configuration', click the 'Configure LDAP +' button, and add a new LDAP config linked to the domain you just created.

[[ceo]] handles the creation of CloudStack accounts, so create an API key + secret token and add it to /etc/csc/ceod.ini on biloba.

=== Templates ===
This deserves an entire page of its own - see [[CloudStack Templates]].

=== Kubernetes ===
This deserves an entire page of its own - see [[Kubernetes]].

== Upgrading CloudStack ==
Please be extremely careful if you decide to upgrade CloudStack. The last time I tried to perform an upgrade (from 4.15 to 4.16), the agents refused to connect to the management servers (or maybe it was the other way around?), and I ended up having to wipe the entire CloudStack installation clean and start again from scratch. Therefore it is fair to say that nobody has ever managed to successfully upgrade CloudStack on our machines. Do this at your own risk.

If you decide to perform an upgrade, then at the very least, you will need to backup the MariaDB databases ('cloud' and 'cloud_usage'), as well as the /etc/cloudstack and /var/lib/cloudstack folders on each of biloba, chamomile and ginkgo. Also, good luck.

== Siracha Crash Out Notes ==
If you ever find your self in the unfourtunate position of needing to recover from a drive failure. It's JOEVER BRO TRUST ME.

Anyways this is what I've learned from the pits of hell

# Our nginx config is funny, and it redirects 9987 → gunicorn → ceod instance running on server
## If the drive dies, ask someone with a backup for just a zip file, it's not possible to recover. Trust me
# you need to reload both nginx & cloudstack to get it running
# You need the crt to get it working (stored under `/etc/csc/k8s` (I think)

== Crash Out Notes Cont. ==
The user console on CloudStack was not working.

In Chamomile <code>/etc/nginx/sites-enabled</code>, you can see a list of all user websites that are enabled. There's a file entitled <code>consoleproxy.cloud.csclub.uwaterloo.ca</code> in which you will find that the console proxy is being hosted on the VM with IP <code>172.19.134.59</code> on CloudStack.

Run the following command whilst in Chamomile to access the console proxy:

<code>sudo ssh -i /var/lib/cloudstack/management/.ssh/id_rsa -p 3922 169.254.35.150</code>

More information on troubleshooting the console and console proxy can be found [https://cwiki.apache.org/confluence/display/CLOUDSTACK/View+Console+and+Console+Proxy+Troubleshooting here.]

Web Hosting

2025-06-30T17:02:08Z

K57chan: /* Fighting AI scrappers */

The CSC offers web hosting for [[Club Hosting|clubs]] and [http://csclub.uwaterloo.ca/about/ our members] in accordance with our [http://csclub.uwaterloo.ca/services/machine_usage Machine Usage Agreement]. This is a quick guide for the kinds of hosting we offer on our webserver, <tt>csclub.uwaterloo.ca</tt>, also known as [[Machine List#caffeine|caffeine]].

We run an Apache httpd webserver and we offer you the use of a [[MySQL|MySQL database]].

== What can I host on my website? ==

Web hosting is provided in accordance with the CSC [http://csclub.uwaterloo.ca/services/machine_usage Machine Usage Agreement]. As a reminder, you are '''not permitted''' to host any of the following:

* '''Ads.''' Advertisements are not permitted because using our machines for commercial purposes is forbidden by university policy.
* '''Your start-up's website.''' Again, commercial use of our hosting is not permitted.
* '''Unauthorized copyrighted materials.''' Violating the law is a violation of our Machine Usage Agreement.

Please note that '''this is not an exhaustive list. Websites may be taken down ''without notice''''' at the discretion of the Systems Committee. (We will always let you know that we took your site down, but if it is breaking our shared environment, we can't provide an advance warning.)

Some great examples of things members host on our webserver:

* Academic projects!
* A personal website or blog!
* [[Club Hosting|Club websites!]]

== How do I make a website? ==

If you just want to show some static content (e.g. blog posts, club information, technical articles), then we recommend that you use a static site generator (SSG). Static sites are faster, simpler and more secure than CMSs like WordPress (dynamic and written in PHP) for small sites. We routinely disable WordPress sites that are more than a few weeks out of date (or if a critical security flaw is disclosed).

Here are some SSGs which require little to no coding experience, and also have a great selection of themes to choose from:

* [https://jekyllrb.com/ Jekyll] (accepts Markdown, Liquid and HTML)
* [https://gohugo.io/ Hugo] (accepts a wide variety of formats, including Markdown and JSON)
* [https://hexo.io/ Hexo] (accepts Markdown and various Javascript-based templating engines)
* [https://www.11ty.dev/ Eleventy] (accepts Markdown, Liquid, HTML, and various Javascript-based templating engines)
* [https://www.getzola.org/ Zola] (accepts Markdown and Tera)
* [https://blog.getpelican.com/ Pelican] (accepts Markdown, reStructuredText and Jinja2)

[https://astro.build/ Astro] is an excellent static site builder which integrates with a wide variety of JS-based frameworks (including React, Vue, Svelte and Solid), but requires a bit more coding experience.

These SSGs require some experience with React.js:

* [https://nextjs.org/ Next.js]
* [https://www.gatsbyjs.com/ Gatsby.js]

These SSGs require some experience with Vue.js:

* [https://nuxtjs.org/ Nuxt.js]
* [https://vuepress.vuejs.org/ Vuepress]
* [https://vitepress.vuejs.org/ Vitepress]
* [https://gridsome.org/ Gridsome]

[https://jamstack.org/generators/ Here] is an awesome list of other generators to explore, if you are interested.

=== Transferring your files to the CSC servers ===
If you just need to transfer a single file, then the easiest option is to use the <code>scp</code> command (which is available on all major operating systems), e.g.

scp /path/to/your/file your_username@corn-syrup.csclub.uwaterloo.ca:~/

This will copy /path/to/your/file from your local PC to your CSC home directory (we use NFS, so you can access it from any of the general-use machines).

However, we strongly recommend setting up a git repository in your home directory instead.

=== Setting up a git repository ===
All of the files in the <code>www</code> directory in your home directory are accessible from csclub.uwaterloo.ca/~your_username. If everything is set up right, this can provide a GitHub Pages-like experience.

<ol>
<li>
<ul>
<li>For members: 
Create a "bare" git repository in your home directory (on the CSC machines). You will git push/pull from this directory.
<pre>
mkdir myrepo.git
cd myrepo.git
git init --bare
</pre>
</li>
<li>For club reps: 
Switch to the Unix user for your club, and use the <code>--shared</code> option to automatically add group write permissions.
<pre>
become_club myclub
cd ~
mkdir myrepo.git
cd myrepo.git
git init --bare --shared
</pre>
</li>
</ul>
</li>
<li>
Create a git post-receive hook which will automatically deploy your website whenever you git push. Paste the following script into hooks/post-receive (in the bare repo you created earlier). You may wish to customize it a bit first.
<pre>
#!/bin/bash

set -e
# Uncomment this to echo the commands as they are executed
#set -x
shopt -s dotglob
# FOR CLUB REPS ONLY: set the following variable to e.g. /users/myclub/www
DEPLOYMENT_DIR=~/www

while read oldrev newrev refname; do
branch=$(git rev-parse --symbolic --abbrev-ref $refname)
# Only the master branch will be deployed
if [ "$branch" != master ]; then
continue
fi
rm -rf $DEPLOYMENT_DIR/*
git --work-tree=$DEPLOYMENT_DIR checkout -f $branch
# FOR CLUB REPS ONLY: uncomment the following lines and replace 'myclub'
# with the Unix group name of your club
#chgrp -R myclub $DEPLOYMENT_DIR
#chmod -R g+w $DEPLOYMENT_DIR
done
</pre>
(The script was adapted from [https://peteris.rocks/blog/deploy-your-website-with-git/ here].)

Make the script executable:
<pre>
chmod +x hooks/post-receive
</pre>

For club reps: Make sure the www directory is group-writable. Switch to the Unix user of your club and run:
<pre>
chmod g+w ~/www
</pre>
</li>
<li>
If you have not done so already, add your public SSH key to your ~/.ssh/authorized_keys file (on the CSC machines). See [https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key here] for a tutorial.
</li>
<li>
On your local computer, add [[Machine_List|any CSC machine]] as a remote of your git repo.
<ul>
<li>For members: 
Just use the directory of your git repo, e.g.
<pre>
git remote add csc your_username@corn-syrup.csclub.uwaterloo.ca:myrepo.git
</pre>
</li>
<li>For club reps: 
Use the full path of the repo in your club user's home directory, e.g.
<pre>
git remote add csc your_username@corn-syrup.csclub.uwaterloo.ca:/users/myclub/myrepo.git
</pre>
</li>
</ul>
</li>
<li>
Now you can just <code>git push</code> normally after a commit, e.g.
<pre>
git push csc master
</pre>
And the files should show up automatically in your www folder (or your club's www folder, if you are a club rep).
</li>
<li>
If you have any files in your repo which you don't want to be served from your website, use a [https://httpd.apache.org/docs/2.4/howto/htaccess.html .htaccess file] in your www folder (make sure this is committed to the git repo). For example, to deny access to the folder named src (in your www folder), you could use the following snippet:
<pre>
RewriteEngine On
RewriteRule "^src(/.*)?$" - [F,L]
</pre>
See [https://httpd.apache.org/docs/2.4/mod/core.html the Apache documentation] for more details.
</li>
</ol>

If you need help, email <tt>syscom@csclub.uwaterloo.ca[mailto:syscom@csclub.uwaterloo.ca]</tt> or come to the CS Club office on the MC 3rd floor across from the Mathsoc CnD.

== DNS and Your Domain Name ==

You can serve files without any additional configuration by placing them in your <tt>www</tt> directory and accessing them at <tt>http://csclub.uwaterloo.ca/~userid</tt>, where <tt>userid</tt> is your CSC user ID. However, many of our members and clubs prefer to use a custom domain name.

Note that this means you ''do not'' have to register a domain name to be able to use our services. You can just put a website at <tt>http://csclub.uwaterloo.ca/~userid</tt>.

=== uwaterloo.ca domain Names ===

If you represent a UWaterloo organization, you may be eligible for a custom <tt>uwaterloo.ca</tt> domain name, such as <tt>csclub.uwaterloo.ca</tt>. We can request this on your behalf.

In order to do so, we must have verified that the organization is a legitimate UWaterloo-affiliated group, and that you, the representative, are authorized to request a domain name on their behalf. This all takes place when you request [[Club Hosting|club hosting]] with the Computer Science Club.

Once you register as a club representative of your particular organization, you can send an email from your official club account to syscom@csclub.uwaterloo.ca to request the domain <tt>yourdomain.uwaterloo.ca</tt>. Assuming it is available, we will file a ticket and request the domain in your name.

=== Your personal domain name ===

These virtual hosts must be approved by the Executive and Systems Committee. If interested, send syscom@csclub.uwaterloo.ca an email. If your request is approved, the Systems Committee will direct you to create a CNAME record for your domain and point it at <tt>csclub.uwaterloo.ca</tt>.

If you are interested in receiving mail or having other records on your domain, the apex of your domain cannot be a CNAME. If this is the case, then your domain should contain an "A" record of <tt>129.97.134.17</tt> and a (optional, but recommended) "AAAA" record of <tt>2620:101:f000:4901:c5c::caff:e12e</tt>.

If you want TLS on your personal domain, mention this in your email to syscom (syscom: see [[SSL#letsencrypt]]).

== Static Sites ==

You can place all your static content into your web directory, <tt>/users/userid/www</tt>.

If you have been approved for a virtual host, you can access this content using your personal domain once the Systems Committee makes the appropriate configuration changes. Here is an example configuration file:

<VirtualHost *:80>
ServerName foobar.uwaterloo.ca
ServerAlias *.foobar.uwaterloo.ca foobar
ServerAdmin your@email.here.tld

DocumentRoot /users/userid/www/

ErrorLog /var/log/apache2/luser-userid-error.log
CustomLog /var/log/apache2/luser-userid-access.log combined
</VirtualHost>

== Dynamic Sites ==

If you require use of a database, we offer you the sole choice of MySQL. See [[MySQL|this guide]] for how to create your database and connect to MySQL.

=== ***NOTICE*** ===

We '''STRONGLY''' discourage the use of content management systems such as
WordPress. These packages are notorious for the number of security
vulnerabilities they contain and pose a threat to our systems if they are not
kept up to date. The Systems Committee '''WILL,''' at its discretion, disable
any website using a package such as WordPress that is not updated to the latest
version or that is found to contain exploitable security flaws. In such a case,
the member or club serving that site will be notified of the termination; the
site will not be re-enabled until the issues are addressed.

When pages are parked, access to them is restricted to on-campus IPs, so you can still fix your page, but anyone off-campus will not be able to access it, and will be shown this page instead: [https://csclub.uwaterloo.ca/~sysadmin/insecure/ https://csclub.uwaterloo.ca/~sysadmin/insecure/].

=== Using PHP ===

Because we use Apache, it's as simple as placing your <tt>index.php</tt> file in your <tt>/users/userid/www</tt>. That's it!

You can even include rewrite rules in an <tt>.htaccess</tt> file in your web directory.

=== Reverse Proxy (Python, Ruby, Perl, etc.) ===

(In progress... Cliff Notes below)

If computationally expensive, please run the server on a general-use server and proxy to Caffeine.

If Python, (1) use a [http://docs.python-guide.org/en/latest/dev/virtualenvs/ virtual environment] (2) host your app (within the virtualenv) with [http://gunicorn.org/ Gunicorn] on a high port (but campus firewalled, i.e. NOT Ports 28000-28500).

If Ruby (Note, I've never used Ruby so take this with a grain of salt), use [http://unicorn.bogomips.org/ Unicorn] in the same way.

==== .htaccess Config ====

Put the following in the appropriate .htaccess file (e.g. if you were running your app at ~ctdalek/python-app, put the .htaccess in ~ctdalek/www/python-app alongside the static files). Replace HOST with localhost if running on Caffeine or the hostname if running elsewhere; replace port with your chosen port number.

<pre>
RewriteEngine On

# If you want websockets, uncomment this:
#RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
#RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
#RewriteRule .* ws://HOST:RANDOM_PORT%{REQUEST_URI} [L,P]

RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule "index.html" "http://HOST:RANDOM_PORT/" [P]

RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule "^(.*)$" "http://HOST:RANDOM_PORT/$1" [P]
</pre>

== Requiring Authentication ==
**UPDATE**: CAS is deprecated; the instructions below are left for historical purposes only. The University of Waterloo now uses [[ADFS]] for web authentication. Unfortunately the Apache module which we use to integrate with ADFS (mod_auth_mellon) cannot be used from .htaccess files, which means that regular members cannot use this. ([https://github.com/latchset/mod_auth_mellon/issues/82 Here] is the relevant GitHub issue; as of this writing, it is still open.) If you require UW authentication for your website, please send an email to syscom and we will configure Apache for you.

=== CAS (no longer works) ===
You can require users to authenticate through the University's Central Authentication System (CAS) by adding the following contents to your .htaccess configuration file:

<pre>
AuthType CAS
Require valid-user
</pre>

You can replace <pre>Require valid-user</pre> with <pre>Require user ctdalek</pre> to restrict to specific users. See https://doubledoublesecurity.ca/uw/cas/user.html for more information.

== Syscom ==

=== Disabling insecure or infringing sites ===

To disable a webspace that has known security vulnerabilities add the following snippet to `/etc/apache2/conf-available/disable-vuln-site.conf`. This rewrites all accesses of the directory or its children to the given file. Note that our disable page always returns HTTP status code 503 (Service Unavailable).

<Directory /users/$BADUSER/www>
AllowOverride None
Redirect 503 /
ErrorDocument 503 /~sysadmin/insecure/index.html
</Directory>

For infringing sites:

<Directory "/users/$BADUSER/www/infringing-directory">
AllowOverride None
Redirect 503 /
ErrorDocument 503 /~sysadmin/infringing/index.html
</Directory>

For club domains (e.g. club1.uwaterloo.ca), redirect to the CSC domain instead:

<Directory "/users/$BADCLUB/www">
AllowOverride None
RewriteEngine On
RewriteRule . <nowiki>https://csclub.uwaterloo.ca/~sysadmin/insecure/index.php</nowiki> [L,P]
</Directory>

For WordPress sites specifically, insert a snippet similar to the following into conf-enabled/disable-wordpress.conf:

<Directory "/users/$BADCLUB/www">
Include snippets/disable-wordpress.conf
</Directory>

=== Expired Websites ===

There is a cron job running hourly on caffeine which disables expired member's websites (and re-enables them when they've renewed their membership).

The script is here: https://git.csclub.uwaterloo.ca/public/expire-sites

Some highlights:

* The script provides a 1-month grace period (corresponding to the grace period of pam-csc)
* The expired page returns HTTP status code of 503 (Service Unavailable)

=== Fighting AI scrappers ===
We use [https://github.com/TecharoHQ/anubis Anubis] to block excess AI scrappers. This sits between Apache2 and the real application to insert a proof-of-work challenge for the browser to solve, before proceeding to provide the actual content.

Since Anubis requires JavaScript, it is only selectively enabled on sites that a) is currently getting excessively scraped and b) need JavaScript already.

Currently, only [[Git Hosting]] is protected.

See <code>caffeine:/etc/anubis</code> for details.

Anubis might break services running on the CSC servers (e.g. Renovate Bot). To fix this, simply add the service into the list of Anubis' exceptions (gitea.botPolicies.json). Afterwards, restart Anubis, Apache, and Gitea.

=== Sample Apache config for website with both a custom domain and a UW subdomain ===

Define ENTITY_NAME pmclub
Define CUSTOM_DOMAIN puremath.club
Define UW_SUBDOMAIN ${ENTITY_NAME}.uwaterloo.ca
Define ADMIN_EMAIL ${ENTITY_NAME}@csclub.uwaterloo.ca
Define ENTITY_HOME https://csclub.uwaterloo.ca/~${ENTITY_NAME}

Define APACHE_LOG_DIR /var/log/apache2
Define ERROR_LOG ${APACHE_LOG_DIR}/${ENTITY_NAME}-error.log
Define CUSTOM_LOG "${APACHE_LOG_DIR}/${ENTITY_NAME}-access.log combined"

<VirtualHost *:80>
ServerName ${CUSTOM_DOMAIN}
ServerAlias *.${CUSTOM_DOMAIN} ${UW_SUBDOMAIN} *.${UW_SUBDOMAIN} ${ENTITY_NAME}
ServerAdmin ${ADMIN_EMAIL}

Redirect permanent / https://${CUSTOM_DOMAIN}/

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}
</VirtualHost>

<VirtualHost csclub:443>
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/${CUSTOM_DOMAIN}/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/${CUSTOM_DOMAIN}/privkey.pem
SSLStrictSNIVHostCheck on

ServerName ${CUSTOM_DOMAIN}
ServerAlias *.${CUSTOM_DOMAIN}
ServerAdmin ${ADMIN_EMAIL}

DocumentRoot /users/${ENTITY_NAME}/www

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}

Redirect permanent /<special page> ${ENTITY_HOME}/<special path>/<special file>
</VirtualHost>

<VirtualHost csclub:443>
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/${UW_SUBDOMAIN}/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/${UW_SUBDOMAIN}/privkey.pem
SSLStrictSNIVHostCheck on

ServerName ${UW_SUBDOMAIN}
ServerAlias *.${UW_SUBDOMAIN}
ServerAdmin ${ADMIN_EMAIL}

Redirect permanent / https://${CUSTOM_DOMAIN}/

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}
</VirtualHost>

Web Hosting

2025-06-28T00:08:59Z

K57chan:

The CSC offers web hosting for [[Club Hosting|clubs]] and [http://csclub.uwaterloo.ca/about/ our members] in accordance with our [http://csclub.uwaterloo.ca/services/machine_usage Machine Usage Agreement]. This is a quick guide for the kinds of hosting we offer on our webserver, <tt>csclub.uwaterloo.ca</tt>, also known as [[Machine List#caffeine|caffeine]].

We run an Apache httpd webserver and we offer you the use of a [[MySQL|MySQL database]].

== What can I host on my website? ==

Web hosting is provided in accordance with the CSC [http://csclub.uwaterloo.ca/services/machine_usage Machine Usage Agreement]. As a reminder, you are '''not permitted''' to host any of the following:

* '''Ads.''' Advertisements are not permitted because using our machines for commercial purposes is forbidden by university policy.
* '''Your start-up's website.''' Again, commercial use of our hosting is not permitted.
* '''Unauthorized copyrighted materials.''' Violating the law is a violation of our Machine Usage Agreement.

Please note that '''this is not an exhaustive list. Websites may be taken down ''without notice''''' at the discretion of the Systems Committee. (We will always let you know that we took your site down, but if it is breaking our shared environment, we can't provide an advance warning.)

Some great examples of things members host on our webserver:

* Academic projects!
* A personal website or blog!
* [[Club Hosting|Club websites!]]

== How do I make a website? ==

If you just want to show some static content (e.g. blog posts, club information, technical articles), then we recommend that you use a static site generator (SSG). Static sites are faster, simpler and more secure than CMSs like WordPress (dynamic and written in PHP) for small sites. We routinely disable WordPress sites that are more than a few weeks out of date (or if a critical security flaw is disclosed).

Here are some SSGs which require little to no coding experience, and also have a great selection of themes to choose from:

* [https://jekyllrb.com/ Jekyll] (accepts Markdown, Liquid and HTML)
* [https://gohugo.io/ Hugo] (accepts a wide variety of formats, including Markdown and JSON)
* [https://hexo.io/ Hexo] (accepts Markdown and various Javascript-based templating engines)
* [https://www.11ty.dev/ Eleventy] (accepts Markdown, Liquid, HTML, and various Javascript-based templating engines)
* [https://www.getzola.org/ Zola] (accepts Markdown and Tera)
* [https://blog.getpelican.com/ Pelican] (accepts Markdown, reStructuredText and Jinja2)

[https://astro.build/ Astro] is an excellent static site builder which integrates with a wide variety of JS-based frameworks (including React, Vue, Svelte and Solid), but requires a bit more coding experience.

These SSGs require some experience with React.js:

* [https://nextjs.org/ Next.js]
* [https://www.gatsbyjs.com/ Gatsby.js]

These SSGs require some experience with Vue.js:

* [https://nuxtjs.org/ Nuxt.js]
* [https://vuepress.vuejs.org/ Vuepress]
* [https://vitepress.vuejs.org/ Vitepress]
* [https://gridsome.org/ Gridsome]

[https://jamstack.org/generators/ Here] is an awesome list of other generators to explore, if you are interested.

=== Transferring your files to the CSC servers ===
If you just need to transfer a single file, then the easiest option is to use the <code>scp</code> command (which is available on all major operating systems), e.g.

scp /path/to/your/file your_username@corn-syrup.csclub.uwaterloo.ca:~/

This will copy /path/to/your/file from your local PC to your CSC home directory (we use NFS, so you can access it from any of the general-use machines).

However, we strongly recommend setting up a git repository in your home directory instead.

=== Setting up a git repository ===
All of the files in the <code>www</code> directory in your home directory are accessible from csclub.uwaterloo.ca/~your_username. If everything is set up right, this can provide a GitHub Pages-like experience.

<ol>
<li>
<ul>
<li>For members: 
Create a "bare" git repository in your home directory (on the CSC machines). You will git push/pull from this directory.
<pre>
mkdir myrepo.git
cd myrepo.git
git init --bare
</pre>
</li>
<li>For club reps: 
Switch to the Unix user for your club, and use the <code>--shared</code> option to automatically add group write permissions.
<pre>
become_club myclub
cd ~
mkdir myrepo.git
cd myrepo.git
git init --bare --shared
</pre>
</li>
</ul>
</li>
<li>
Create a git post-receive hook which will automatically deploy your website whenever you git push. Paste the following script into hooks/post-receive (in the bare repo you created earlier). You may wish to customize it a bit first.
<pre>
#!/bin/bash

set -e
# Uncomment this to echo the commands as they are executed
#set -x
shopt -s dotglob
# FOR CLUB REPS ONLY: set the following variable to e.g. /users/myclub/www
DEPLOYMENT_DIR=~/www

while read oldrev newrev refname; do
branch=$(git rev-parse --symbolic --abbrev-ref $refname)
# Only the master branch will be deployed
if [ "$branch" != master ]; then
continue
fi
rm -rf $DEPLOYMENT_DIR/*
git --work-tree=$DEPLOYMENT_DIR checkout -f $branch
# FOR CLUB REPS ONLY: uncomment the following lines and replace 'myclub'
# with the Unix group name of your club
#chgrp -R myclub $DEPLOYMENT_DIR
#chmod -R g+w $DEPLOYMENT_DIR
done
</pre>
(The script was adapted from [https://peteris.rocks/blog/deploy-your-website-with-git/ here].)

Make the script executable:
<pre>
chmod +x hooks/post-receive
</pre>

For club reps: Make sure the www directory is group-writable. Switch to the Unix user of your club and run:
<pre>
chmod g+w ~/www
</pre>
</li>
<li>
If you have not done so already, add your public SSH key to your ~/.ssh/authorized_keys file (on the CSC machines). See [https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key here] for a tutorial.
</li>
<li>
On your local computer, add [[Machine_List|any CSC machine]] as a remote of your git repo.
<ul>
<li>For members: 
Just use the directory of your git repo, e.g.
<pre>
git remote add csc your_username@corn-syrup.csclub.uwaterloo.ca:myrepo.git
</pre>
</li>
<li>For club reps: 
Use the full path of the repo in your club user's home directory, e.g.
<pre>
git remote add csc your_username@corn-syrup.csclub.uwaterloo.ca:/users/myclub/myrepo.git
</pre>
</li>
</ul>
</li>
<li>
Now you can just <code>git push</code> normally after a commit, e.g.
<pre>
git push csc master
</pre>
And the files should show up automatically in your www folder (or your club's www folder, if you are a club rep).
</li>
<li>
If you have any files in your repo which you don't want to be served from your website, use a [https://httpd.apache.org/docs/2.4/howto/htaccess.html .htaccess file] in your www folder (make sure this is committed to the git repo). For example, to deny access to the folder named src (in your www folder), you could use the following snippet:
<pre>
RewriteEngine On
RewriteRule "^src(/.*)?$" - [F,L]
</pre>
See [https://httpd.apache.org/docs/2.4/mod/core.html the Apache documentation] for more details.
</li>
</ol>

If you need help, email <tt>syscom@csclub.uwaterloo.ca[mailto:syscom@csclub.uwaterloo.ca]</tt> or come to the CS Club office on the MC 3rd floor across from the Mathsoc CnD.

== DNS and Your Domain Name ==

You can serve files without any additional configuration by placing them in your <tt>www</tt> directory and accessing them at <tt>http://csclub.uwaterloo.ca/~userid</tt>, where <tt>userid</tt> is your CSC user ID. However, many of our members and clubs prefer to use a custom domain name.

Note that this means you ''do not'' have to register a domain name to be able to use our services. You can just put a website at <tt>http://csclub.uwaterloo.ca/~userid</tt>.

=== uwaterloo.ca domain Names ===

If you represent a UWaterloo organization, you may be eligible for a custom <tt>uwaterloo.ca</tt> domain name, such as <tt>csclub.uwaterloo.ca</tt>. We can request this on your behalf.

In order to do so, we must have verified that the organization is a legitimate UWaterloo-affiliated group, and that you, the representative, are authorized to request a domain name on their behalf. This all takes place when you request [[Club Hosting|club hosting]] with the Computer Science Club.

Once you register as a club representative of your particular organization, you can send an email from your official club account to syscom@csclub.uwaterloo.ca to request the domain <tt>yourdomain.uwaterloo.ca</tt>. Assuming it is available, we will file a ticket and request the domain in your name.

=== Your personal domain name ===

These virtual hosts must be approved by the Executive and Systems Committee. If interested, send syscom@csclub.uwaterloo.ca an email. If your request is approved, the Systems Committee will direct you to create a CNAME record for your domain and point it at <tt>csclub.uwaterloo.ca</tt>.

If you are interested in receiving mail or having other records on your domain, the apex of your domain cannot be a CNAME. If this is the case, then your domain should contain an "A" record of <tt>129.97.134.17</tt> and a (optional, but recommended) "AAAA" record of <tt>2620:101:f000:4901:c5c::caff:e12e</tt>.

If you want TLS on your personal domain, mention this in your email to syscom (syscom: see [[SSL#letsencrypt]]).

== Static Sites ==

You can place all your static content into your web directory, <tt>/users/userid/www</tt>.

If you have been approved for a virtual host, you can access this content using your personal domain once the Systems Committee makes the appropriate configuration changes. Here is an example configuration file:

<VirtualHost *:80>
ServerName foobar.uwaterloo.ca
ServerAlias *.foobar.uwaterloo.ca foobar
ServerAdmin your@email.here.tld

DocumentRoot /users/userid/www/

ErrorLog /var/log/apache2/luser-userid-error.log
CustomLog /var/log/apache2/luser-userid-access.log combined
</VirtualHost>

== Dynamic Sites ==

If you require use of a database, we offer you the sole choice of MySQL. See [[MySQL|this guide]] for how to create your database and connect to MySQL.

=== ***NOTICE*** ===

We '''STRONGLY''' discourage the use of content management systems such as
WordPress. These packages are notorious for the number of security
vulnerabilities they contain and pose a threat to our systems if they are not
kept up to date. The Systems Committee '''WILL,''' at its discretion, disable
any website using a package such as WordPress that is not updated to the latest
version or that is found to contain exploitable security flaws. In such a case,
the member or club serving that site will be notified of the termination; the
site will not be re-enabled until the issues are addressed.

When pages are parked, access to them is restricted to on-campus IPs, so you can still fix your page, but anyone off-campus will not be able to access it, and will be shown this page instead: [https://csclub.uwaterloo.ca/~sysadmin/insecure/ https://csclub.uwaterloo.ca/~sysadmin/insecure/].

=== Using PHP ===

Because we use Apache, it's as simple as placing your <tt>index.php</tt> file in your <tt>/users/userid/www</tt>. That's it!

You can even include rewrite rules in an <tt>.htaccess</tt> file in your web directory.

=== Reverse Proxy (Python, Ruby, Perl, etc.) ===

(In progress... Cliff Notes below)

If computationally expensive, please run the server on a general-use server and proxy to Caffeine.

If Python, (1) use a [http://docs.python-guide.org/en/latest/dev/virtualenvs/ virtual environment] (2) host your app (within the virtualenv) with [http://gunicorn.org/ Gunicorn] on a high port (but campus firewalled, i.e. NOT Ports 28000-28500).

If Ruby (Note, I've never used Ruby so take this with a grain of salt), use [http://unicorn.bogomips.org/ Unicorn] in the same way.

==== .htaccess Config ====

Put the following in the appropriate .htaccess file (e.g. if you were running your app at ~ctdalek/python-app, put the .htaccess in ~ctdalek/www/python-app alongside the static files). Replace HOST with localhost if running on Caffeine or the hostname if running elsewhere; replace port with your chosen port number.

<pre>
RewriteEngine On

# If you want websockets, uncomment this:
#RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
#RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
#RewriteRule .* ws://HOST:RANDOM_PORT%{REQUEST_URI} [L,P]

RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule "index.html" "http://HOST:RANDOM_PORT/" [P]

RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule "^(.*)$" "http://HOST:RANDOM_PORT/$1" [P]
</pre>

== Requiring Authentication ==
**UPDATE**: CAS is deprecated; the instructions below are left for historical purposes only. The University of Waterloo now uses [[ADFS]] for web authentication. Unfortunately the Apache module which we use to integrate with ADFS (mod_auth_mellon) cannot be used from .htaccess files, which means that regular members cannot use this. ([https://github.com/latchset/mod_auth_mellon/issues/82 Here] is the relevant GitHub issue; as of this writing, it is still open.) If you require UW authentication for your website, please send an email to syscom and we will configure Apache for you.

=== CAS (no longer works) ===
You can require users to authenticate through the University's Central Authentication System (CAS) by adding the following contents to your .htaccess configuration file:

<pre>
AuthType CAS
Require valid-user
</pre>

You can replace <pre>Require valid-user</pre> with <pre>Require user ctdalek</pre> to restrict to specific users. See https://doubledoublesecurity.ca/uw/cas/user.html for more information.

== Syscom ==

=== Disabling insecure or infringing sites ===

To disable a webspace that has known security vulnerabilities add the following snippet to `/etc/apache2/conf-available/disable-vuln-site.conf`. This rewrites all accesses of the directory or its children to the given file. Note that our disable page always returns HTTP status code 503 (Service Unavailable).

<Directory /users/$BADUSER/www>
AllowOverride None
Redirect 503 /
ErrorDocument 503 /~sysadmin/insecure/index.html
</Directory>

For infringing sites:

<Directory "/users/$BADUSER/www/infringing-directory">
AllowOverride None
Redirect 503 /
ErrorDocument 503 /~sysadmin/infringing/index.html
</Directory>

For club domains (e.g. club1.uwaterloo.ca), redirect to the CSC domain instead:

<Directory "/users/$BADCLUB/www">
AllowOverride None
RewriteEngine On
RewriteRule . <nowiki>https://csclub.uwaterloo.ca/~sysadmin/insecure/index.php</nowiki> [L,P]
</Directory>

For WordPress sites specifically, insert a snippet similar to the following into conf-enabled/disable-wordpress.conf:

<Directory "/users/$BADCLUB/www">
Include snippets/disable-wordpress.conf
</Directory>

=== Expired Websites ===

There is a cron job running hourly on caffeine which disables expired member's websites (and re-enables them when they've renewed their membership).

The script is here: https://git.csclub.uwaterloo.ca/public/expire-sites

Some highlights:

* The script provides a 1-month grace period (corresponding to the grace period of pam-csc)
* The expired page returns HTTP status code of 503 (Service Unavailable)

=== Fighting AI scrappers ===
We use [https://github.com/TecharoHQ/anubis Anubis] to block excess AI scrappers. This sits between Apache2 and the real application to insert a proof-of-work challenge for the browser to solve, before proceeding to provide the actual content.

Since Anubis requires JavaScript, it is only selectively enabled on sites that a) is currently getting excessively scraped and b) need JavaScript already.

Currently, only [[Git Hosting]] is protected.

See <code>caffeine:/etc/anubis</code> for details.

Anubis might break services running on the CSC servers (e.g. Renovate Bot). To fix this, simply add the service into the list of Anubis' exceptions (gitea.botPolicies.json). Afterwards, restart Anubis and Apache. WARNING: This might break Git.

=== Sample Apache config for website with both a custom domain and a UW subdomain ===

Define ENTITY_NAME pmclub
Define CUSTOM_DOMAIN puremath.club
Define UW_SUBDOMAIN ${ENTITY_NAME}.uwaterloo.ca
Define ADMIN_EMAIL ${ENTITY_NAME}@csclub.uwaterloo.ca
Define ENTITY_HOME https://csclub.uwaterloo.ca/~${ENTITY_NAME}

Define APACHE_LOG_DIR /var/log/apache2
Define ERROR_LOG ${APACHE_LOG_DIR}/${ENTITY_NAME}-error.log
Define CUSTOM_LOG "${APACHE_LOG_DIR}/${ENTITY_NAME}-access.log combined"

<VirtualHost *:80>
ServerName ${CUSTOM_DOMAIN}
ServerAlias *.${CUSTOM_DOMAIN} ${UW_SUBDOMAIN} *.${UW_SUBDOMAIN} ${ENTITY_NAME}
ServerAdmin ${ADMIN_EMAIL}

Redirect permanent / https://${CUSTOM_DOMAIN}/

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}
</VirtualHost>

<VirtualHost csclub:443>
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/${CUSTOM_DOMAIN}/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/${CUSTOM_DOMAIN}/privkey.pem
SSLStrictSNIVHostCheck on

ServerName ${CUSTOM_DOMAIN}
ServerAlias *.${CUSTOM_DOMAIN}
ServerAdmin ${ADMIN_EMAIL}

DocumentRoot /users/${ENTITY_NAME}/www

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}

Redirect permanent /<special page> ${ENTITY_HOME}/<special path>/<special file>
</VirtualHost>

<VirtualHost csclub:443>
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/${UW_SUBDOMAIN}/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/${UW_SUBDOMAIN}/privkey.pem
SSLStrictSNIVHostCheck on

ServerName ${UW_SUBDOMAIN}
ServerAlias *.${UW_SUBDOMAIN}
ServerAdmin ${ADMIN_EMAIL}

Redirect permanent / https://${CUSTOM_DOMAIN}/

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}
</VirtualHost>

Web Hosting

2025-06-28T00:02:55Z

K57chan: Added documentation on fixing Anubis when it kills other bots.

The CSC offers web hosting for [[Club Hosting|clubs]] and [http://csclub.uwaterloo.ca/about/ our members] in accordance with our [http://csclub.uwaterloo.ca/services/machine_usage Machine Usage Agreement]. This is a quick guide for the kinds of hosting we offer on our webserver, <tt>csclub.uwaterloo.ca</tt>, also known as [[Machine List#caffeine|caffeine]].

We run an Apache httpd webserver and we offer you the use of a [[MySQL|MySQL database]].

== What can I host on my website? ==

Web hosting is provided in accordance with the CSC [http://csclub.uwaterloo.ca/services/machine_usage Machine Usage Agreement]. As a reminder, you are '''not permitted''' to host any of the following:

* '''Ads.''' Advertisements are not permitted because using our machines for commercial purposes is forbidden by university policy.
* '''Your start-up's website.''' Again, commercial use of our hosting is not permitted.
* '''Unauthorized copyrighted materials.''' Violating the law is a violation of our Machine Usage Agreement.

Please note that '''this is not an exhaustive list. Websites may be taken down ''without notice''''' at the discretion of the Systems Committee. (We will always let you know that we took your site down, but if it is breaking our shared environment, we can't provide an advance warning.)

Some great examples of things members host on our webserver:

* Academic projects!
* A personal website or blog!
* [[Club Hosting|Club websites!]]

== How do I make a website? ==

If you just want to show some static content (e.g. blog posts, club information, technical articles), then we recommend that you use a static site generator (SSG). Static sites are faster, simpler and more secure than CMSs like WordPress (dynamic and written in PHP) for small sites. We routinely disable WordPress sites that are more than a few weeks out of date (or if a critical security flaw is disclosed).

Here are some SSGs which require little to no coding experience, and also have a great selection of themes to choose from:

* [https://jekyllrb.com/ Jekyll] (accepts Markdown, Liquid and HTML)
* [https://gohugo.io/ Hugo] (accepts a wide variety of formats, including Markdown and JSON)
* [https://hexo.io/ Hexo] (accepts Markdown and various Javascript-based templating engines)
* [https://www.11ty.dev/ Eleventy] (accepts Markdown, Liquid, HTML, and various Javascript-based templating engines)
* [https://www.getzola.org/ Zola] (accepts Markdown and Tera)
* [https://blog.getpelican.com/ Pelican] (accepts Markdown, reStructuredText and Jinja2)

[https://astro.build/ Astro] is an excellent static site builder which integrates with a wide variety of JS-based frameworks (including React, Vue, Svelte and Solid), but requires a bit more coding experience.

These SSGs require some experience with React.js:

* [https://nextjs.org/ Next.js]
* [https://www.gatsbyjs.com/ Gatsby.js]

These SSGs require some experience with Vue.js:

* [https://nuxtjs.org/ Nuxt.js]
* [https://vuepress.vuejs.org/ Vuepress]
* [https://vitepress.vuejs.org/ Vitepress]
* [https://gridsome.org/ Gridsome]

[https://jamstack.org/generators/ Here] is an awesome list of other generators to explore, if you are interested.

=== Transferring your files to the CSC servers ===
If you just need to transfer a single file, then the easiest option is to use the <code>scp</code> command (which is available on all major operating systems), e.g.

scp /path/to/your/file your_username@corn-syrup.csclub.uwaterloo.ca:~/

This will copy /path/to/your/file from your local PC to your CSC home directory (we use NFS, so you can access it from any of the general-use machines).

However, we strongly recommend setting up a git repository in your home directory instead.

=== Setting up a git repository ===
All of the files in the <code>www</code> directory in your home directory are accessible from csclub.uwaterloo.ca/~your_username. If everything is set up right, this can provide a GitHub Pages-like experience.

<ol>
<li>
<ul>
<li>For members: 
Create a "bare" git repository in your home directory (on the CSC machines). You will git push/pull from this directory.
<pre>
mkdir myrepo.git
cd myrepo.git
git init --bare
</pre>
</li>
<li>For club reps: 
Switch to the Unix user for your club, and use the <code>--shared</code> option to automatically add group write permissions.
<pre>
become_club myclub
cd ~
mkdir myrepo.git
cd myrepo.git
git init --bare --shared
</pre>
</li>
</ul>
</li>
<li>
Create a git post-receive hook which will automatically deploy your website whenever you git push. Paste the following script into hooks/post-receive (in the bare repo you created earlier). You may wish to customize it a bit first.
<pre>
#!/bin/bash

set -e
# Uncomment this to echo the commands as they are executed
#set -x
shopt -s dotglob
# FOR CLUB REPS ONLY: set the following variable to e.g. /users/myclub/www
DEPLOYMENT_DIR=~/www

while read oldrev newrev refname; do
branch=$(git rev-parse --symbolic --abbrev-ref $refname)
# Only the master branch will be deployed
if [ "$branch" != master ]; then
continue
fi
rm -rf $DEPLOYMENT_DIR/*
git --work-tree=$DEPLOYMENT_DIR checkout -f $branch
# FOR CLUB REPS ONLY: uncomment the following lines and replace 'myclub'
# with the Unix group name of your club
#chgrp -R myclub $DEPLOYMENT_DIR
#chmod -R g+w $DEPLOYMENT_DIR
done
</pre>
(The script was adapted from [https://peteris.rocks/blog/deploy-your-website-with-git/ here].)

Make the script executable:
<pre>
chmod +x hooks/post-receive
</pre>

For club reps: Make sure the www directory is group-writable. Switch to the Unix user of your club and run:
<pre>
chmod g+w ~/www
</pre>
</li>
<li>
If you have not done so already, add your public SSH key to your ~/.ssh/authorized_keys file (on the CSC machines). See [https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key here] for a tutorial.
</li>
<li>
On your local computer, add [[Machine_List|any CSC machine]] as a remote of your git repo.
<ul>
<li>For members: 
Just use the directory of your git repo, e.g.
<pre>
git remote add csc your_username@corn-syrup.csclub.uwaterloo.ca:myrepo.git
</pre>
</li>
<li>For club reps: 
Use the full path of the repo in your club user's home directory, e.g.
<pre>
git remote add csc your_username@corn-syrup.csclub.uwaterloo.ca:/users/myclub/myrepo.git
</pre>
</li>
</ul>
</li>
<li>
Now you can just <code>git push</code> normally after a commit, e.g.
<pre>
git push csc master
</pre>
And the files should show up automatically in your www folder (or your club's www folder, if you are a club rep).
</li>
<li>
If you have any files in your repo which you don't want to be served from your website, use a [https://httpd.apache.org/docs/2.4/howto/htaccess.html .htaccess file] in your www folder (make sure this is committed to the git repo). For example, to deny access to the folder named src (in your www folder), you could use the following snippet:
<pre>
RewriteEngine On
RewriteRule "^src(/.*)?$" - [F,L]
</pre>
See [https://httpd.apache.org/docs/2.4/mod/core.html the Apache documentation] for more details.
</li>
</ol>

If you need help, email <tt>syscom@csclub.uwaterloo.ca[mailto:syscom@csclub.uwaterloo.ca]</tt> or come to the CS Club office on the MC 3rd floor across from the Mathsoc CnD.

== DNS and Your Domain Name ==

You can serve files without any additional configuration by placing them in your <tt>www</tt> directory and accessing them at <tt>http://csclub.uwaterloo.ca/~userid</tt>, where <tt>userid</tt> is your CSC user ID. However, many of our members and clubs prefer to use a custom domain name.

Note that this means you ''do not'' have to register a domain name to be able to use our services. You can just put a website at <tt>http://csclub.uwaterloo.ca/~userid</tt>.

=== uwaterloo.ca domain Names ===

If you represent a UWaterloo organization, you may be eligible for a custom <tt>uwaterloo.ca</tt> domain name, such as <tt>csclub.uwaterloo.ca</tt>. We can request this on your behalf.

In order to do so, we must have verified that the organization is a legitimate UWaterloo-affiliated group, and that you, the representative, are authorized to request a domain name on their behalf. This all takes place when you request [[Club Hosting|club hosting]] with the Computer Science Club.

Once you register as a club representative of your particular organization, you can send an email from your official club account to syscom@csclub.uwaterloo.ca to request the domain <tt>yourdomain.uwaterloo.ca</tt>. Assuming it is available, we will file a ticket and request the domain in your name.

=== Your personal domain name ===

These virtual hosts must be approved by the Executive and Systems Committee. If interested, send syscom@csclub.uwaterloo.ca an email. If your request is approved, the Systems Committee will direct you to create a CNAME record for your domain and point it at <tt>csclub.uwaterloo.ca</tt>.

If you are interested in receiving mail or having other records on your domain, the apex of your domain cannot be a CNAME. If this is the case, then your domain should contain an "A" record of <tt>129.97.134.17</tt> and a (optional, but recommended) "AAAA" record of <tt>2620:101:f000:4901:c5c::caff:e12e</tt>.

If you want TLS on your personal domain, mention this in your email to syscom (syscom: see [[SSL#letsencrypt]]).

== Static Sites ==

You can place all your static content into your web directory, <tt>/users/userid/www</tt>.

If you have been approved for a virtual host, you can access this content using your personal domain once the Systems Committee makes the appropriate configuration changes. Here is an example configuration file:

<VirtualHost *:80>
ServerName foobar.uwaterloo.ca
ServerAlias *.foobar.uwaterloo.ca foobar
ServerAdmin your@email.here.tld

DocumentRoot /users/userid/www/

ErrorLog /var/log/apache2/luser-userid-error.log
CustomLog /var/log/apache2/luser-userid-access.log combined
</VirtualHost>

== Dynamic Sites ==

If you require use of a database, we offer you the sole choice of MySQL. See [[MySQL|this guide]] for how to create your database and connect to MySQL.

=== ***NOTICE*** ===

We '''STRONGLY''' discourage the use of content management systems such as
WordPress. These packages are notorious for the number of security
vulnerabilities they contain and pose a threat to our systems if they are not
kept up to date. The Systems Committee '''WILL,''' at its discretion, disable
any website using a package such as WordPress that is not updated to the latest
version or that is found to contain exploitable security flaws. In such a case,
the member or club serving that site will be notified of the termination; the
site will not be re-enabled until the issues are addressed.

When pages are parked, access to them is restricted to on-campus IPs, so you can still fix your page, but anyone off-campus will not be able to access it, and will be shown this page instead: [https://csclub.uwaterloo.ca/~sysadmin/insecure/ https://csclub.uwaterloo.ca/~sysadmin/insecure/].

=== Using PHP ===

Because we use Apache, it's as simple as placing your <tt>index.php</tt> file in your <tt>/users/userid/www</tt>. That's it!

You can even include rewrite rules in an <tt>.htaccess</tt> file in your web directory.

=== Reverse Proxy (Python, Ruby, Perl, etc.) ===

(In progress... Cliff Notes below)

If computationally expensive, please run the server on a general-use server and proxy to Caffeine.

If Python, (1) use a [http://docs.python-guide.org/en/latest/dev/virtualenvs/ virtual environment] (2) host your app (within the virtualenv) with [http://gunicorn.org/ Gunicorn] on a high port (but campus firewalled, i.e. NOT Ports 28000-28500).

If Ruby (Note, I've never used Ruby so take this with a grain of salt), use [http://unicorn.bogomips.org/ Unicorn] in the same way.

==== .htaccess Config ====

Put the following in the appropriate .htaccess file (e.g. if you were running your app at ~ctdalek/python-app, put the .htaccess in ~ctdalek/www/python-app alongside the static files). Replace HOST with localhost if running on Caffeine or the hostname if running elsewhere; replace port with your chosen port number.

<pre>
RewriteEngine On

# If you want websockets, uncomment this:
#RewriteCond %{HTTP:UPGRADE} ^WebSocket$ [NC]
#RewriteCond %{HTTP:CONNECTION} ^Upgrade$ [NC]
#RewriteRule .* ws://HOST:RANDOM_PORT%{REQUEST_URI} [L,P]

RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule "index.html" "http://HOST:RANDOM_PORT/" [P]

RewriteCond %{SCRIPT_FILENAME} !-d
RewriteCond %{SCRIPT_FILENAME} !-f
RewriteRule "^(.*)$" "http://HOST:RANDOM_PORT/$1" [P]
</pre>

== Requiring Authentication ==
**UPDATE**: CAS is deprecated; the instructions below are left for historical purposes only. The University of Waterloo now uses [[ADFS]] for web authentication. Unfortunately the Apache module which we use to integrate with ADFS (mod_auth_mellon) cannot be used from .htaccess files, which means that regular members cannot use this. ([https://github.com/latchset/mod_auth_mellon/issues/82 Here] is the relevant GitHub issue; as of this writing, it is still open.) If you require UW authentication for your website, please send an email to syscom and we will configure Apache for you.

=== CAS (no longer works) ===
You can require users to authenticate through the University's Central Authentication System (CAS) by adding the following contents to your .htaccess configuration file:

<pre>
AuthType CAS
Require valid-user
</pre>

You can replace <pre>Require valid-user</pre> with <pre>Require user ctdalek</pre> to restrict to specific users. See https://doubledoublesecurity.ca/uw/cas/user.html for more information.

== Syscom ==

=== Disabling insecure or infringing sites ===

To disable a webspace that has known security vulnerabilities add the following snippet to `/etc/apache2/conf-available/disable-vuln-site.conf`. This rewrites all accesses of the directory or its children to the given file. Note that our disable page always returns HTTP status code 503 (Service Unavailable).

<Directory /users/$BADUSER/www>
AllowOverride None
Redirect 503 /
ErrorDocument 503 /~sysadmin/insecure/index.html
</Directory>

For infringing sites:

<Directory "/users/$BADUSER/www/infringing-directory">
AllowOverride None
Redirect 503 /
ErrorDocument 503 /~sysadmin/infringing/index.html
</Directory>

For club domains (e.g. club1.uwaterloo.ca), redirect to the CSC domain instead:

<Directory "/users/$BADCLUB/www">
AllowOverride None
RewriteEngine On
RewriteRule . <nowiki>https://csclub.uwaterloo.ca/~sysadmin/insecure/index.php</nowiki> [L,P]
</Directory>

For WordPress sites specifically, insert a snippet similar to the following into conf-enabled/disable-wordpress.conf:

<Directory "/users/$BADCLUB/www">
Include snippets/disable-wordpress.conf
</Directory>

=== Expired Websites ===

There is a cron job running hourly on caffeine which disables expired member's websites (and re-enables them when they've renewed their membership).

The script is here: https://git.csclub.uwaterloo.ca/public/expire-sites

Some highlights:

* The script provides a 1-month grace period (corresponding to the grace period of pam-csc)
* The expired page returns HTTP status code of 503 (Service Unavailable)

=== Fighting AI scrappers ===
We use [https://github.com/TecharoHQ/anubis Anubis] to block excess AI scrappers. This sits between Apache2 and the real application to insert a proof-of-work challenge for the browser to solve, before proceeding to provide the actual content.

Since Anubis requires JavaScript, it is only selectively enabled on sites that a) is currently getting excessively scraped and b) need JavaScript already.

Currently, only [[Git Hosting]] is protected.

See <code>caffeine:/etc/anubis</code> for details.

Anubis might break certain bots running on the CSC servers (e.g. Renovate Bot). To fix this, simply add the service into the list of Anubis' exceptions (gitea.botPolicies.json). This might break Git.

=== Sample Apache config for website with both a custom domain and a UW subdomain ===

Define ENTITY_NAME pmclub
Define CUSTOM_DOMAIN puremath.club
Define UW_SUBDOMAIN ${ENTITY_NAME}.uwaterloo.ca
Define ADMIN_EMAIL ${ENTITY_NAME}@csclub.uwaterloo.ca
Define ENTITY_HOME https://csclub.uwaterloo.ca/~${ENTITY_NAME}

Define APACHE_LOG_DIR /var/log/apache2
Define ERROR_LOG ${APACHE_LOG_DIR}/${ENTITY_NAME}-error.log
Define CUSTOM_LOG "${APACHE_LOG_DIR}/${ENTITY_NAME}-access.log combined"

<VirtualHost *:80>
ServerName ${CUSTOM_DOMAIN}
ServerAlias *.${CUSTOM_DOMAIN} ${UW_SUBDOMAIN} *.${UW_SUBDOMAIN} ${ENTITY_NAME}
ServerAdmin ${ADMIN_EMAIL}

Redirect permanent / https://${CUSTOM_DOMAIN}/

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}
</VirtualHost>

<VirtualHost csclub:443>
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/${CUSTOM_DOMAIN}/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/${CUSTOM_DOMAIN}/privkey.pem
SSLStrictSNIVHostCheck on

ServerName ${CUSTOM_DOMAIN}
ServerAlias *.${CUSTOM_DOMAIN}
ServerAdmin ${ADMIN_EMAIL}

DocumentRoot /users/${ENTITY_NAME}/www

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}

Redirect permanent /<special page> ${ENTITY_HOME}/<special path>/<special file>
</VirtualHost>

<VirtualHost csclub:443>
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/${UW_SUBDOMAIN}/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/${UW_SUBDOMAIN}/privkey.pem
SSLStrictSNIVHostCheck on

ServerName ${UW_SUBDOMAIN}
ServerAlias *.${UW_SUBDOMAIN}
ServerAdmin ${ADMIN_EMAIL}

Redirect permanent / https://${CUSTOM_DOMAIN}/

ErrorLog ${ERROR_LOG}
CustomLog ${CUSTOM_LOG}
</VirtualHost>