docs/admin_handbook.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

<!DOCTYPE html>
<html lang="en">
	<head>
		<title>CCA Admin Handbook</title>
		<link rel="stylesheet" href="./handbook.css" />
		<meta charset="utf-8" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
	</head>
	<body>
		<header>
			<h1>
				CCA Admin Handbook
			</h1>
		</header>
		<main>
			<h2>Introduction</h2>
			<p>
			This handbook guides you in installing, configuring, and managing your CCA Selection System (CCASS) instance.
			</p>
			<h2>Downloading</h2>
			<p>
			You may obtain a stable or development version. The stable version is recommended for production.
			</p>
			<ul>
				<li>To obtain a stable version, go to the <a href="https://git.sr.ht/~runxiyu/cca/refs">release page</a> and download the latest version that is not a pre-release.</li>
				<li>To obtain an unstable development version, clone the development repository at <a href="https://git.sr.ht/~runxiyu/cca"><code>https://git.sr.ht/~runxiyu/cca</code></a>, or download the latest development snapshot&rsquo;s tarball at <a href="https://git.runxiyu.org/ykps/cca.git/snapshot/cca-master.tar.gz"><code>https://git.runxiyu.org/ykps/cca.git/snapshot/cca-master.tar.gz</code></a>.</li>
			</ul>
			<h2>Building</h2>
			<p>
			There is a top-level <code>Makefile</code> that builds the backend. This is all the compilation necessary at the moment; in the future, the front-end code such as the CSS and JavaScript may be minified too.
			</p>
			<p>
			You may also wish to strip the binary&rsquo;s debug symbols to shrink the file size:
			</p>
			<pre>make && strip cca</pre>
			<h2>Configuration</h2>
			<p>
			The <code>static</code> and <code>tmpl</code> directories must be available to the running program, in addition to a configuration file <code>cca.scfg</code>.
			</p>
			<p>
			Copy <a href="./cca.scfg.example">the example configuration file</a> to <code>cca.scfg</code> in the working directory where you intend to run CCASS. Then edit it according to the comments, though you may wish to pay attention to the following:
			</p>
			<ul>
				<li>CCASS natively supports serving over clear text HTTP or over HTTPS. HTTPS is required for production setups as Microsoft Entra ID does not allow clear-text HTTP redirect URLs for non-<code>localhost</code> access.</li>
				<li>Note that CCASS is designed to be directly exposed to clients due to the lacking performance of standard reverse proxy setups, although there is nothing that otherwise prevents it from being used behind a reverse proxy. Reverse proxies must forward WebSocket connection upgrade headers for all requests to the <code>/ws</code> endpoint.</li>
				<li>You must <a href="https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade">create an app registration on the Azure portal</a> and complete the corresponding configuration options.</li>
				<li>You must configure a <a href="https://www.postgresql.org/">PostgreSQL</a> instance and configure CCASS accordingly.</li>
				<li><code>perf/sendq</code> should be set to roughly the number of expected students making concurrent choices.</li>
			</ul>
		</main>
	</body>
</html>