1
0
Fork 0
forked from TWS/kalkutago

Add README

This commit is contained in:
D. Scott Boggs 2023-06-25 11:30:45 -04:00
parent e33ce8b1a8
commit e84e9e6594

60
README.md Normal file
View file

@ -0,0 +1,60 @@
# Kalkutago
A multi-user Tickmate clone for the web
## Development
### Before you start
The backend uses a postgres server which is not tracked as a part of the
repository, and neither is the password for it. You'll need to generate a
password by doing something like
```console
openssl rand -base64 36 > server/postgres.pw
```
The development environment uses Traefik to reverse-proxy the API and dev
server. In production, the API will serve the client directly, but this system
allows you to run the dev server behind a reverse proxy so that changes are
rendered quickly without having to rebuild the container. Using the vite dev
server also gets us better debugging in the browser.
However, that means that Traefik needs a hostname to listen for. The way I've
done this is by adding the following entry to my `/etc/hosts` file:
```
127.0.0.1 kalkutago
```
### Server
The server is written in Rust, using Rocket and SeaOrm. It uses Rust nightly, so
you'll need to `rustup override set nightly`, though it gets built in docker so
you really only need this for IDE support.
### Client
The client is a Vue application. It has a central state in
[`state.ts`](client/src/state.ts). On application load, the state is initialized
by fetching the current tracks and ticks via the API, and then subscribes to
updates from the server by opening an EventSource at `/api/v1/updates`.
The basic flow is:
- a user interaction happens which should trigger a state change
- the action is dispatched to the server (e.g. by making a PATCH request to
`/api/v1/tracks/<track_id>/ticked`)
- the server makes the appropriate change to the database
- an event is dispatched to the event sources subscribed via `/api/v1/updates`
- The client receives the event, the reactive state is updated, and the UI
changes to match the expected state.
### Running for development
`docker-compose_dev.yml` is symlinked to `docker-compose.yml` for now, so once
the hostname is set up Just run `docker-compose up --build` and visit
http://kalkutago/ to open the app
### Populating the database
In order to see the UI components I add a track to the database like
```console
curl --json '{"name": "test", "description": "test track", "icon": "❓", "enabled": 1}' kalkutago/api/v1/tracks
```