diff options
| -rw-r--r-- | Makefile | 11 | ||||
| -rw-r--r-- | docs/admin_handbook.html | 62 | ||||
| -rw-r--r-- | docs/admin_handbook.md | 45 | ||||
| -rwxr-xr-x | scripts/latexify-source.sh | 2 |
4 files changed, 50 insertions, 70 deletions
@@ -6,12 +6,12 @@ default: dist/cca docs iadocs cca: dist/cca -docs: dist/docs/admin_handbook.html dist/docs/handbook.css dist/docs/cca.scfg.example +docs: dist/docs/admin_handbook.html dist/docs/cca.scfg.example iadocs: dist/iadocs/index.html dist/iadocs/cover_page.htm dist/iadocs/appendix.pdf dist/iadocs/crita_planning.pdf dist/iadocs/critb_design.pdf dist/iadocs/critb_recordoftasks.htm dist/iadocs/critc_development.pdf dist/iadocs/critd_functionality.pdf dist/iadocs/crite_evaluation.pdf # Final binary which tries to embed stuff -dist/cca: go.* *.go build/static/style.css build/static/student.js templates/* build/docs/admin_handbook.html build/docs/handbook.css build/docs/cca.scfg.example build/iadocs/index.html build/iadocs/cover_page.htm build/iadocs/appendix.pdf build/iadocs/crita_planning.pdf build/iadocs/critb_design.pdf build/iadocs/critb_recordoftasks.htm build/iadocs/critc_development.pdf build/iadocs/critd_functionality.pdf build/iadocs/crite_evaluation.pdf .editorconfig .gitignore .gitattributes scripts/* sql/* docs/* iadocs/* README.md LICENSE Makefile +dist/cca: go.* *.go build/static/style.css build/static/student.js templates/* build/docs/admin_handbook.html build/docs/cca.scfg.example build/iadocs/index.html build/iadocs/cover_page.htm build/iadocs/appendix.pdf build/iadocs/crita_planning.pdf build/iadocs/critb_design.pdf build/iadocs/critb_recordoftasks.htm build/iadocs/critc_development.pdf build/iadocs/critd_functionality.pdf build/iadocs/crite_evaluation.pdf .editorconfig .gitignore .gitattributes scripts/* sql/* docs/* iadocs/* README.md LICENSE Makefile mkdir -p dist go build -o $@ @@ -19,12 +19,9 @@ dist/cca: go.* *.go build/static/style.css build/static/student.js templates/* b dist/docs/%: build/docs/% mkdir -p dist/docs cp $< $@ -build/docs/%.html: docs/%.html +build/docs/%.html: docs/%.md docs/handbook.css mkdir -p build/docs - minify --html-keep-end-tags --html-keep-document-tags -o $@ $< -build/docs/handbook.css: docs/handbook.css - mkdir -p build/docs - minify -o $@ $< + pandoc --embed-resources --wrap none --standalone -t html -f markdown --css docs/handbook.css $< | minify --type html -o $@ build/docs/cca.scfg.example: docs/cca.scfg.example mkdir -p build/docs cp $< $@ diff --git a/docs/admin_handbook.html b/docs/admin_handbook.html deleted file mode 100644 index 765d4bb..0000000 --- a/docs/admin_handbook.html +++ /dev/null @@ -1,62 +0,0 @@ -<!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’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>External dependencies</h2> - <p> - You need a <a href="https://go.dev">Go</a> toolchain, <a href="https://pygments.org/">Pygments</a>, <a href="https://www.gnu.org/software/make/">GNU make</a>, <a href="https://tug.org/texlive/">TeX Live</a> and <a href="https://github.com/tdewolff/minify">minify</a>. If you have everything else, you could install minify via <code>make minifier</code>, which would build and install it with your Go toolchain. - </p> - <p> - The Go toolchain will fetch more dependencies. You may wish to set a Go proxy (such as via <code>export GOPROXY='https://goproxy.io'</code>) if it stalls or is too slow. This is likely necessary for users in Mainland China due to firewall restrictions. - </p> - <h2>Building</h2> - <p>Just type <code>make</code>.</p> - <p> - The built files will appear in <code>dist/</code>. The binary, with all runtime resources other than the configuration file embedded, is located at <code>dist/cca</code>. A minified copy of the documentation, including a sample configuration file, is located at <code>dist/docs/</code>. - </p> - <h2>Configuration</h2> - <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><code>perf/sendq</code> should be set to roughly the number of expected students making concurrent choices.</li> - </ul> - <h2>Database setup</h2> - <p> - A working PostgreSQL setup is required. It is recommended to set up UNIX socket authentication and set the user running CCASS as the database owner while creating the database. - </p> - <p> - Before first run, run <code>psql <i>dbname</i> -f sql/schema.sql</code> to create the database tables, where <code><i>dbname</i></code> is the name of the database. - </p> - <p> - Using the same database for different versions of CCASS is currently unsupported, although it should be trivial to manually migrate the database. - </p> - </main> - </body> -</html> diff --git a/docs/admin_handbook.md b/docs/admin_handbook.md new file mode 100644 index 0000000..25d0c74 --- /dev/null +++ b/docs/admin_handbook.md @@ -0,0 +1,45 @@ +--- +lang: en +title: CCA Admin Handbook +viewport: width=device-width, initial-scale=1 +--- + +## Introduction + +This handbook guides you in installing, configuring, and managing your CCA Selection System (CCASS) instance. + +## Downloading + +You may obtain a stable or development version. The stable version is recommended for production. + +- To obtain a stable version, go to the [release page](https://git.sr.ht/~runxiyu/cca/refs) and download the latest version that is not a pre-release. +- To obtain an unstable development version, clone the development repository at [`https://git.sr.ht/~runxiyu/cca`](https://git.sr.ht/~runxiyu/cca), or download the latest development snapshot's tarball at [`https://git.runxiyu.org/ykps/cca.git/snapshot/cca-master.tar.gz`](https://git.runxiyu.org/ykps/cca.git/snapshot/cca-master.tar.gz). + +## External dependencies + +You need a [Go](https://go.dev) toolchain, [Pygments](https://pygments.org/), [GNU make](https://www.gnu.org/software/make/), [TeX Live](https://tug.org/texlive/) and [minify](https://github.com/tdewolff/minify). If you have everything else, you could install minify via `make minifier`, which would build and install it with your Go toolchain. + +The Go toolchain will fetch more dependencies. You may wish to set a Go proxy (such as via `export GOPROXY='https://goproxy.io'`) if it stalls or is too slow. This is likely necessary for users in Mainland China due to firewall restrictions. + +## Building + +Just type `make`. + +The built files will appear in `dist/`. The binary, with all runtime resources other than the configuration file embedded, is located at `dist/cca`. A minified copy of the documentation, including a sample configuration file, is located at `dist/docs/`. + +## Configuration + +Copy [the example configuration file](./cca.scfg.example) to `cca.scfg` 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: + +- 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-`localhost` access. +- 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 `/ws` endpoint. +- You must [create an app registration on the Azure portal](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) and complete the corresponding configuration options. +- `perf/sendq` should be set to roughly the number of expected students making concurrent choices. + +## Database setup + +A working PostgreSQL setup is required. It is recommended to set up UNIX socket authentication and set the user running CCASS as the database owner while creating the database. + +Before first run, run <code>psql <i>dbname</i> -f sql/schema.sql</code> to create the database tables, where <code><i>dbname</i></code> is the name of the database. + +Using the same database for different versions of CCASS is currently unsupported, although it should be trivial to manually migrate the database. diff --git a/scripts/latexify-source.sh b/scripts/latexify-source.sh index 5198e95..1766465 100755 --- a/scripts/latexify-source.sh +++ b/scripts/latexify-source.sh @@ -40,7 +40,7 @@ chapter SQL scripts include_code postgresql 8 sql/*.sql chapter Production documentation -include_code html 2 docs/*.html +include_code markdown 2 docs/*.md include_code css 8 docs/*.css include_code text 8 docs/*.csv docs/cca.scfg.example |