openmood

Crates.ioopenmood
lib.rsopenmood
version0.5.0
sourcesrc
created_at2023-12-21 13:13:54.688283
updated_at2024-02-22 20:50:24.163591
descriptionModular mood tracker backend
homepage
repositoryhttps://codeberg.org/OpenThingies/openmood
max_upload_size
id1076901
size528,316
Emma (FallenValkyrie)

documentation

README

OpenMood

Build Status Crates.io MSRV Crates.io Version Crates.io License

Openmood is a self-hosted, modular mood tracker.

Most mood trackers seem to allow a simple numeric score between one and however many smileys they display and/or just a plaintext field. Now, for some people this may be enough, but if that isn't enough for you, that's what openmood is for.

  • It's FOSS (yay, woo 🎉)
  • It allows you to customize the data you wish to track.
    • Simple Text fields
    • Text selections
    • Numeric input
  • You have full control over your data, because you own the server it runs on.
  • Don't like the frontends we provide? Feel free to suggest improvements or even make your own.

Table of Contents

Install from crates.io

Requirements

Installation

  1. run cargo install openmood
  2. the server binary will now be available as openmood
  3. run the server and configure it

Install from source

Requirements

  • Rust toolchain
  • You must have a postgres database running (PostgreSQL 16.0+)
  • git So you can actually download the code

Building the server

  1. Clone the repository:
$ git clone https://codeberg.org/OpenThingies/openmood.git
$ cd openmood
  1. Build and install the server
$ cargo install --path .

The binary is now available as openmood. To see how you can configure openmood, look at Configuration

Development

Requirements

  • Rust toolchain (Stable)
    • rustfmt (nightly)
    • clippy (stable)
  • docker-compose To spin up a pre-configured development environment.
  • knope To generate changesets and changelogs
  • Optional: cargo-watch this allows reloading the server on code changes.
  • Optional: the sqlx-cli binary to apply migrations manually. (useful when running tests from a blank database)

Development Environment

Just run the docker compose up in the project to spin up all necessary dependencies including PgAdmin for convenience. NOTE: this is to be used for development purposes only

When using the docker compose, you can access a local postgres DB and a PgAdmin instance. They can be accessed with the following config:

  • the postgres URI is: postgres://postgres:123456@localhost
  • the credentials for PgAdmin are: dev@developer.dev with password 123456

Required Environment Variables

If you wish to set additional config options, go to Configuration

  • OM_DB_URI must be set to whatever URI you use to connect to your postgres instance.
  • OM_JWT_SECRET Can be set to any string during development.
  • RUST_LOG This isn't required, but I recommend to set it to at least openmood=debug,actix=info,jealousy=info,sqlx=info.

Running the server

If you have cargo-watch installed, you can have it automatically reload the server as you change the code.

Note: using cargo watch may give minor issues if you are writing migrations, because they will be applied as the server reloads. If you run into this issue, the easiest thing to do is reset the database and reapply the migrations using sqlx migrate run --database-url [your db URI] or restarting the server and automatically apply the embedded migrations.

# with cargo-watch installed
cargo watch -cqx run

# without cargo-watch installed
cargo run

Configuration

All configuration is done via environment variables. What follows is a list of all possible environment variables one can set.

Env Var Description Required Default
RUST_LOG The log level you wish to set. you can either set the severity globally with RUST_LOG=info or you can set it per module RUST_LOG=openmood=info, comma separating each item. The levels can be one of error, warn, info, debug, trace No error
OM_PORT The port that the server will bind to No 3000
OM_BIND_ADDR The IP the server will bind to No 0.0.0.0
OM_DB_URI The postgres Database URI Yes
OM_JWT_SECRET The 256-bit JWT secret you wish to use to sign JWT tokens. Please make sure to use a sufficiently random string. Yes
OM_JWT_PERM_VALIDITY The amount of days a "permanent" JWT token is valid for. This is used when a user ticks the "stay logged in" checkbox No 7
OM_JWT_TMP_VALIDITY The amount of hours a "temporary" JWT token is valid for No 3
OM_ADMIN_USER A comma separated list of key-value pairs that holds the data to be used to build an initial admin user. An example of this is name:test,username:my_cool_username,password:some super C00l P@$$W0rd. Whitespace is allowed, just be careful since it is not filtered from keys nor values.

NOTE: This will not overwrite or change an existing user. To do that, you need to set OM_ADMIN_USER_OVERRIDE to true
No
OM_ADMIN_USER_OVERRIDE Allows to mutate an existing user, making them an admin in the process. Doing so will only change the admin flag. It will not change the user's name, nor their email. no false
OM_CORS_ALLOWED_ORIGINS A comma separated list of the origins that are allowed to access this API. This is mainly for the browser and should therefore contain the URIs from which the frontend may be accessed.

Note that the default value for this is different in development than it is in Release. In release it i only accepts requests from the same origin, whereas in debug mode it accepts connections from the frontend.
No Development: http://localhost:5173,http://127.0.0.1:5173
Release: same-origin
OM_DISABLE_REGISTRATIONS Allows disabling the endpoint that handles registrations to prevent new users from registering No false

License

This project is licensed under the AGPL 3.0 license

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in openmood by you, shall be licensed as AGPL 3.0, without any additional terms or conditions.

Commit count: 0

cargo fmt