doc: update readme for release
This commit is contained in:
parent
7f5941ba6a
commit
2774c6e48a
102
README.md
102
README.md
@ -1,69 +1,49 @@
|
||||
# Brass
|
||||
A webservice to plan and organize personnel deployment for [Brandsicherheitswachen](https://de.wikipedia.org/wiki/Brandsicherheitswache) (german; fire watch).
|
||||
|
||||
# Key Technologies
|
||||
- [actix-web](https://actix.rs/)
|
||||
- [sqlx](https://github.com/launchbadge/sqlx)
|
||||
- [askama](https://github.com/askama-rs/askama)
|
||||
- [lettre](https://lettre.rs/)
|
||||
- [htmx](https://htmx.org/)
|
||||
- [hyperscript](https://hyperscript.org/)
|
||||
- [bulma](https://bulma.io/)
|
||||
- great inspiration for project structure and tooling: [gerust.rs](https://gerust.rs)
|
||||
|
||||
# Getting started with developing
|
||||
1. Clone the repository.
|
||||
2. Install and configure Postgresql. Create a new database for brass: `createdb brass`.
|
||||
3. TODO: Configure DB name, DB user & pass, DB connection string, ...
|
||||
4. Install sqlx-cli: `cargo install sqlx-cli`
|
||||
5. Migrate the database: `sqlx database setup`
|
||||
6. Create superuse: `cargo r -- createadmin`
|
||||
3. Configure database connection string in `.env` config file.
|
||||
4. Install required development tools `cargo install <tool>`
|
||||
- sqlx-cli
|
||||
- mailtutan
|
||||
- cargo-watch
|
||||
- cargo-nextest
|
||||
6. Migrate the development and test database: `cargo db migrate -e development` & `cargo db migrate -e test`
|
||||
7. Create superuser: `cargo r -- createadmin`
|
||||
8. Run and recompile application on file change: `cargo w`
|
||||
9. Run tests via nextest and review possible snapshot changes: `cargo t`
|
||||
|
||||
## Useful stuff
|
||||
- cargo-watch, cargo-add
|
||||
- mailtutan
|
||||
# Build & Deploy
|
||||
1. Clone the repository.
|
||||
2. Build release `cargo b --release`.
|
||||
3. Copy the artifact `target/release/brass-web` to the desired location. Make it executable `chmod +x brass-web`.
|
||||
4. Create Postgresql database on the target host, configure your mail server.
|
||||
5. Configuration for Brass is done via Environment Variables, see `.env` for a list.
|
||||
6. Migrate the database `[LIST_OF_ENV_VARIABLES] brass-web migrate`.
|
||||
7. Create a superuser `[LIST_OF_ENV_VARIABLES] brass-web createadmin`.
|
||||
8. Create some sort of service file (systemd .service, openbsd rc.conf, ...) to run Brass in the background. Examples can be found in `docs/` directory.
|
||||
|
||||
# Contributing & Issues
|
||||
Code lies on my private gitea instance, thus there's no easy way for creating issues or making contributions. If you've got an issue or want to contribute, write me an email and we'll figure it out.
|
||||
|
||||
## Example Deployment OpenBSD
|
||||
```
|
||||
#!/bin/ksh
|
||||
# Project Structure
|
||||
- TODO
|
||||
|
||||
DATABASE_URL=postgresql://brass:pw@localhost/brass
|
||||
SECRET_KEY=""
|
||||
HOSTNAME="brass.tfld.de"
|
||||
SERVER_ADDRESS="127.0.0.1"
|
||||
SERVER_PORT="8081"
|
||||
SMTP_SERVER="localhost"
|
||||
SMTP_PORT="25"
|
||||
SMTP_TLSTYPE="none"
|
||||
ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE"
|
||||
RUST_LOG="info,actix_server=error"
|
||||
# Further Reading
|
||||
More in depth documentation about design decisions, helpful commands and database schema can be found in `docs/` directory.
|
||||
|
||||
ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_LOGIN=$SMTP_LOGIN SMTP_PASSWORD=$SMTP_PASSWORD SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE RUST_LOG=$RUST_LOG"
|
||||
|
||||
daemon="$ENVLIST /usr/local/bin/brass"
|
||||
daemon_user="www"
|
||||
daemon_logger="daemon.info"
|
||||
|
||||
. /etc/rc.d/rc.subr
|
||||
|
||||
pexp=".*/usr/local/bin/brass.*"
|
||||
|
||||
rc_bg=YES
|
||||
|
||||
rc_cmd $1
|
||||
```
|
||||
|
||||
|
||||
```ini
|
||||
# Postgres
|
||||
# DATABASE_URL=postgres://postgres@localhost/my_database
|
||||
# SQLite
|
||||
DATABASE_URL=postgresql://brass:password@localhost/brass
|
||||
# 64 byte long
|
||||
SECRET_KEY="secret key"
|
||||
HOSTNAME="brass.tfld.de"
|
||||
ADDRESS="127.0.0.1"
|
||||
PORT="8081"
|
||||
|
||||
SMTP_SERVER="localhost"
|
||||
SMTP_PORT="25"
|
||||
# SMTP_LOGIN=""
|
||||
# SMTP_PASSWORD=""
|
||||
SMTP_TLSTYPE="none"
|
||||
```
|
||||
|
||||
## drop test databases
|
||||
```bash
|
||||
for dbname in $(psql -c "copy (select datname from pg_database where datname like 'brass_test_%') to stdout") ; do
|
||||
echo "$dbname"
|
||||
#dropdb -i "$dbname"
|
||||
done
|
||||
```
|
||||
# Copyright & License
|
||||
Copyright 2025 Max Hohlfeld
|
||||
Brass is licensed under [GNU AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html#license-text).
|
||||
|
||||
8
doc/drop_test_databases.md
Normal file
8
doc/drop_test_databases.md
Normal file
@ -0,0 +1,8 @@
|
||||
# Drop all test databases
|
||||
|
||||
```bash
|
||||
for dbname in $(psql -c "copy (select datname from pg_database where datname like 'brass_test_%') to stdout") ; do
|
||||
echo "$dbname"
|
||||
#dropdb -i "$dbname"
|
||||
done
|
||||
```
|
||||
31
doc/example_deployment_openbsd.md
Normal file
31
doc/example_deployment_openbsd.md
Normal file
@ -0,0 +1,31 @@
|
||||
# Example Deployment OpenBSD
|
||||
- list of env variables may not be up to date
|
||||
|
||||
```sh
|
||||
#!/bin/ksh
|
||||
|
||||
DATABASE_URL=postgresql://brass:pw@localhost/brass
|
||||
SECRET_KEY=""
|
||||
HOSTNAME="brass.tfld.de"
|
||||
SERVER_ADDRESS="127.0.0.1"
|
||||
SERVER_PORT="8081"
|
||||
SMTP_SERVER="localhost"
|
||||
SMTP_PORT="25"
|
||||
SMTP_TLSTYPE="none"
|
||||
ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE"
|
||||
RUST_LOG="info,actix_server=error"
|
||||
|
||||
ENVLIST="DATABASE_URL=$DATABASE_URL SECRET_KEY=$SECRET_KEY HOSTNAME=$HOSTNAME SERVER_ADDRESS=$SERVER_ADDRESS SERVER_PORT=$SERVER_PORT SMTP_SERVER=$SMTP_SERVER SMTP_LOGIN=$SMTP_LOGIN SMTP_PASSWORD=$SMTP_PASSWORD SMTP_PORT=$SMTP_PORT SMTP_TLSTYPE=$SMTP_TLSTYPE RUST_LOG=$RUST_LOG"
|
||||
|
||||
daemon="$ENVLIST /usr/local/bin/brass"
|
||||
daemon_user="www"
|
||||
daemon_logger="daemon.info"
|
||||
|
||||
. /etc/rc.d/rc.subr
|
||||
|
||||
pexp=".*/usr/local/bin/brass.*"
|
||||
|
||||
rc_bg=YES
|
||||
|
||||
rc_cmd $1
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user