Add README
This commit is contained in:
parent
e33ce8b1a8
commit
e84e9e6594
60
README.md
Normal file
60
README.md
Normal 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
|
||||||
|
```
|
Loading…
Reference in a new issue