From e9af4bfd86c13dcc78cd053eb72c0f5faaf7b1c6 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Sat, 15 Oct 2022 21:31:11 +0200 Subject: [PATCH] Improve documentation --- Makefile | 4 +-- README.md | 73 +++++++++++++++++++++++++++++++++++------------- debian/copyright | 2 +- 3 files changed, 56 insertions(+), 23 deletions(-) diff --git a/Makefile b/Makefile index 589e5ff..3ae51ce 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ lint: golangci-lint run clean: - rm -f cacert-boardvoting + rm -rf cacert-boardvoting dist/ debian/README.md.gz ui/static/semantic.min.css: ${UIFILES} npm install @@ -24,4 +24,4 @@ ui/static/semantic.min.css: ${UIFILES} ui: ui/static/semantic.min.css -.PHONY: clean all ui test lint \ No newline at end of file +.PHONY: clean all ui test lint diff --git a/README.md b/README.md index 6d27faa..f2c97b8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # CAcert board voting service -This project contains the source code for the CAcert board voting software. +This project contains the source code for the CAcert board voting software running on https://motion.cacert.org/. ## Ideas @@ -56,7 +56,7 @@ Local development requires * golang >= 1.18 * sqlite3 and development headers * GNU make -* nodejs, npm and gulp (only needed if you intend to update the [jQuery] or [Semantic UI] CSS and JavaScript) +* nodejs, npm and gulp (only needed if you intend to update the [jQuery] or [Fomantic-UI] CSS and JavaScript) On a Debian 12 (Bookworm) system you can run the following command to get all required dependencies: @@ -74,7 +74,7 @@ git clone ssh://git.cacert.org/var/cache/git/cacert-boardvoting.git To get started copy `config.yaml.example` to `config.yaml` and customize the parameters. You will also need a set of X.509 certificates and a private key because the application performs TLS Client certificate authentication. You might -use `openssl` to create a self signed server certificate and retrieve the CAcert class 3 root from the CAcert website: +use `openssl` to create a self-signed server certificate and retrieve the CAcert class 3 root from the CAcert website: ```shell script openssl req -new -newkey rsa:2048 -keyout server.key -x509 -out server.crt -subj '/CN=localhost' @@ -110,7 +110,7 @@ dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 ### Debugging SMTP server -You can use [aiosmtpd](https://aiosmtpd.readthedocs.io/en/latest/cli.html) to setup a small testing SMTP +You can use [aiosmtpd](https://aiosmtpd.readthedocs.io/en/latest/cli.html) to set up a small testing SMTP server that logs to stdout: ```shell script @@ -118,6 +118,9 @@ sudo apt install python3-aiosmtpd python3 -m aiosmtpd -n ``` +Another good local SMTP debugging tool is [MailHog](https://github.com/mailhog/MailHog) which provides a web based +user interface and a REST API to inspect received mails. + ### Build and run ```shell script @@ -127,7 +130,7 @@ make ### Build UI resources -[Fomantic-UI](https://fomantic-ui.com/) is used as a CSS framework. Configuration is stored in `semantic.json` in the +[Fomantic-UI] is used as a CSS framework. Configuration is stored in `semantic.json` in the project root directory. Building the UI resource requires @@ -146,26 +149,56 @@ npx gulp build ## Code structure ``` -. -├── boardvoting +├── cmd +│   └── boardvoting +├── config.yaml.example +├── debian +├── go.mod +├── go.sum +├── internal +│   ├── app +│   ├── forms +│   ├── handlers +│   ├── jobs +│   ├── mailtemplates +│   ├── mailtemplates.go +│   ├── middleware │   ├── migrations -│   ├── static -│   └── templates -├── db -└── semantic +│   ├── migrations.go +│   ├── models +│   ├── notifications +│   └── validator +├── Jenkinsfile +├── LICENSE +├── Makefile +├── package.json +├── package-lock.json +├── README.md +├── semantic.json +└── ui + ├── efs.go + ├── html + ├── semantic + └── static ``` -The `boardvoting` directory contains the application code, database migrations, static assets and [Go templates] for -HTML pages and mail content. +The `cmd/boardvoting` directory contains the application code. -The `db` directory contains the initializer for database migrations. +The `internal/migrations` directory contains database migration scripts. -The `semantic` directory contains a download of [Semantic UI] +Static assets and [Go templates] for HTML pages are stored in `ui/static` and `ui/html`. -The entry point into the application is `boardvoting.go` in the top level directory. `Makefile` controls the build -`Jenkinsfile` contains the pipeline definition for the [Continuous Integration Job]. `package-lock.json` contains the -pinned versions of external JavaScript and CSS assets (use `npm install` to download them into a local `node_modules` -directory). `semantic.json` is the configuration file for the [Semantic UI] CSS framework. +Email templates are stored in `internal/mailtemplates`. + +All Go code besides the main application is stored in subdirectories of `internal`. + +The `ui/semantic` directory contains a download of [Fomantic-UI]. + +The entry point into the application is `cmd/boardvoting/main.go`. `Makefile` controls the build +`Jenkinsfile` contains the pipeline definition for the [Continuous Integration Job]. +`package-lock.json` contains the pinned versions of external JavaScript and CSS assets (use +`npm install` to download them into a local `node_modules` directory). `semantic.json` is the +configuration file for the [Fomantic-UI] CSS framework. [Continuous Integration Job]: https://jenkins.cacert.org/job/cacert-boardvoting/ @@ -175,4 +208,4 @@ directory). `semantic.json` is the configuration file for the [Semantic UI] CSS [jQuery]: https://jquery.com/ -[Semantic UI]: https://semantic-ui.com/ +[Fomantic-UI]: https://fomantic-ui.com/ \ No newline at end of file diff --git a/debian/copyright b/debian/copyright index 5dcf085..696dcc9 100644 --- a/debian/copyright +++ b/debian/copyright @@ -1,7 +1,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Upstream-Name: CAcert board voting software Upstream-Contact: Jan Dittberner -Source: https://git.cacert.org/gitweb/?p=cacert-boardvoting.git +Source: https://code.cacert.org/cacert/cacert-boardvoting.git Files: * Copyright: 2017-2022 Jan Dittberner