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