forked from TWS/kalkutago
60 lines
2.2 KiB
Markdown
60 lines
2.2 KiB
Markdown
|
# 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
|
||
|
|
```
|