diff --git a/README.md b/README.md index 357b173..cd517a0 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ This project contains the source code for the CAcert board voting software. ## Ideas -The board voting system is meant to be used by the voted board of CAcert Inc. to allow them to do votes on decisions in -a distributed way. The system keeps track of the individual decisions and votes. It takes care of authenticating board -members using client certificates and performs timekeeping for decisions. The system sends voting requests to all board -members and takes care of sending reminders as well es decision results. +The board voting system is meant to be used by the elected committee members of CAcert Inc. to allow them to do votes on +decisions in a distributed way. The system keeps track of the individual decisions and votes. It takes care of +authenticating board members using client certificates and performs timekeeping for decisions. The system sends voting +requests to all board members and takes care of sending reminders as well es decision results. There is a concept of proxy votes that mean that one member of the board is allowed to vote in representation of another member of a board. @@ -16,19 +16,16 @@ member of a board. The CAcert board voting software is licensed under the terms of the Apache License, Version 2.0. - Copyright 2017-2021 Jan Dittberner +Copyright 2017-2022 Jan Dittberner - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this program except in compliance with the License. - You may obtain a copy of the License at +Licensed under the Apache License, Version 2.0 (the "License"); you may not use this program except in compliance with +the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " +AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific +language governing permissions and limitations under the License. ## History @@ -56,12 +53,12 @@ Last Changed Date: 2009-07-12 04:02:38 +0000 (Sun, 12 Jul 2009) Local development requires -* golang >= 1.16 +* golang >= 1.17 * 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) -On a Debian 10 (Buster) system you can run the following command to get all required dependencies: +On a Debian 12 (Bookworm) system you can run the following command to get all required dependencies: ```bash sudo apt install libsqlite3-dev golang-go make gulp @@ -88,20 +85,20 @@ It is advisable to have a local mail setup that intercepts outgoing email or to You can use the following table to find useful values for the parameters in `config.yaml`. -Parameter | Description | How to get a valid value -----------|-------------|------------------------- -`notice_mail_address` | email address where notifications about votes are sent (production value is cacert-board@lists.cacert.org) | be creative but do not spam others (i.e. use user+board@your-domain.org) -`vote_notice_mail_address` | email address where notifications about individual votes are sent (production value is cacert-board-votes@lists.cacert.org) | be creative but do not spam others (i.e. use user+votes@your-domain.org) -`notification_sender_address` | sender address for all mails sent by the system (production value is returns@cacert.org) | be creative but do not spam others (i.e. use user+returns@your-domain.org) -`database_file` | a SQLite database file (production value is `database.sqlite`) | keep the default or use something like `local.sqlite` -`client_ca_certificates` | File containing allowed client certificate CA certificates (production value is `cacert_class3.pem`) | use the shell code above -`server_certificate` | X.509 certificate that is used to identify your server (i.e. `server.crt`) | use the filename used as `-out` parameter in the `openssl` invocation above -`server_key` | PEM encoded private key file (i.e. `server.key`) | use the filename used as `-keyout` parameter in the `openssl` invocation above -`cookie_secret` | A base64 encoded random byte value of at least 32 bytes used to encrypt cookies | see [Generating random byte values](#generating-random-byte-values) below -`csrf_key` | A base64 encoded random byte value of at least 32 bytes used to encrypt [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Prevention) tokens | see [Generating random byte values](#generating-random-byte-values) below -`base_url` | The base URL of your application instance (production value is https://motions.cacert.org) | use https://localhost:8443 -`mail_server.host` | Mail server host (production value is `localhost`) | `localhost` -`mail_server.port` | Mail server TCP port (production value is `25` | see [how to setup a debugging SMTP server](#debugging-smtp-server) below and choose the port of that (default `8025`) +| Parameter | Description | How to get a valid value | +|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| +| `notice_mail_address` | email address where notifications about votes are sent (production value is cacert-board@lists.cacert.org) | be creative but do not spam others (i.e. use user+board@your-domain.org) | +| `vote_notice_mail_address` | email address where notifications about individual votes are sent (production value is cacert-board-votes@lists.cacert.org) | be creative but do not spam others (i.e. use user+votes@your-domain.org) | +| `notification_sender_address` | sender address for all mails sent by the system (production value is returns@cacert.org) | be creative but do not spam others (i.e. use user+returns@your-domain.org) | +| `database_file` | a SQLite database file (production value is `database.sqlite`) | keep the default or use something like `local.sqlite` | +| `client_ca_certificates` | File containing allowed client certificate CA certificates (production value is `cacert_class3.pem`) | use the shell code above | +| `server_certificate` | X.509 certificate that is used to identify your server (i.e. `server.crt`) | use the filename used as `-out` parameter in the `openssl` invocation above | +| `server_key` | PEM encoded private key file (i.e. `server.key`) | use the filename used as `-keyout` parameter in the `openssl` invocation above | +| `cookie_secret` | A base64 encoded random byte value of at least 32 bytes used to encrypt cookies | see [Generating random byte values](#generating-random-byte-values) below | +| `csrf_key` | A base64 encoded random byte value of at least 32 bytes used to encrypt [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Prevention) tokens | see [Generating random byte values](#generating-random-byte-values) below | +| `base_url` | The base URL of your application instance (production value is https://motions.cacert.org) | use https://localhost:8443 | +| `mail_server.host` | Mail server host (production value is `localhost`) | `localhost` | +| `mail_server.port` | Mail server TCP port (production value is `25` | see [how to setup a debugging SMTP server](#debugging-smtp-server) below and choose the port of that (default `8025`) | ### Generating random byte values @@ -111,7 +108,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/aiosmtpd/docs/cli.html) to setup a small testing SMTP +You can use [aiosmtpd](https://aiosmtpd.readthedocs.io/en/latest/cli.html) to setup a small testing SMTP server that logs to stdout: ```shell script @@ -151,7 +148,11 @@ pinned versions of external JavaScript and CSS assets (use `npm install` to down directory). `semantic.json` is the configuration file for the [Semantic UI] CSS framework. [Continuous Integration Job]: https://jenkins.cacert.org/job/cacert-boardvoting/ + [Go]: https://golang.org/ + [Go templates]: https://golang.org/pkg/text/template/ + [jQuery]: https://jquery.com/ + [Semantic UI]: https://semantic-ui.com/