A set of utilities to manage shared lists
- Lists of items with optionally amounts
- Sharing of lists read/write or readonly
- History of entered items to support autocompletion
- Enable public (readonly) viewing of lists
- Make wishlists where items ticked to not appear ticked to the wisher
- Make pantries in order to restock all items under a target in a list
- API Server powering the different clients
- CLI
- Web App
- Android Application
- Admin Tool used to manage the database without the API server
There are no public instances, you will need to host your own.
- [Docker][#docker]
- [From Source][#source]
In case you want to build more tools with kabalist there are some helpers:
- Crate for common Types
- Rust HTTP client crate
- Dart HTTP client (auto-generated from the OpenAPI documentation)
Right now the rust crates are not documented, and the dart-client
documentation is only auto-generated.
The OpenAPI specification for the API server is queryable from the server, at the route <domain>/api-doc/openapi.json
.
The OpenAPI is also available through the swagger-ui at <domain>/swagger-ui/
.
The easiest way to get started is to use the docker_compose.yml
file. You will just need docker and docker-compose.
You can then run docker-compose up
and it will start the postgres database with the kabalist server.
No users exist by default, so you will need to create a registration. You can run docker-compose exec -it database kb_admin registration new
, and copy the generated id.
You can then access http://localhost:8080/register/<id>
in order to create your user.
You use the kb_admin
tool for other administrative tasks, like getting all the users. You can run docker-compose exec -it database kb_admin help
for more information.
- rust & cargo
- PostgreSQL
- trunk (only for the web app)
- flutter (only for the android application)
- sqlx cli (only needed for developpement)
You will then need to create a PostgreSQL database, and export the variable DATABASE_URL=postgres://<user>:<password>@localhost/<db-name>
.
You will need to activate the following postgres extensions: pgcrypto
, citext
, uuid-ossp
(you can run CREATE EXTENSION [IF NOT EXISTS ] <name>
).
You will then need to apply the migrations using sqlx migrate run
in the api/sqlx directory.
You will need to edit the endpoint definition file endpoint definition.
This is only needed for:
- The android application
- The Web Application if it is not served from the same domain as the API Server
You can then run a cargo build --release
to generate the CLI, API Server and Admin Tool. This can use the DATABASE_URL
variable, to check SQL queries against the DB at compile time.
You can build the web application simply by running trunk build --release
in the web directory. This will produce a dist
directory that can be deployed (see the Deploy section)
You will need to go in the flutter directory and execute the prepare.sh
script in order take into account the endpoint.
You can then run flutter build apk --no-tree-shake-icons
to build the android application (the output will indicate the built apk location).
You will need to deploy the binary and api/public to a location. You will also need to provide a KabaList.toml
, you can use the example file.
You should have something like this:
/opt/kabalist
├── kabalist_api
├── public
│ └── public_list.html.tera
└── Rocket.toml
If you want to deploy the frontend using the same application you can also add the dist
folder:
/opt/kabalist
├── dist
│ ├── index.html
│ ├── kabalist-d741b2826776e6b4.css
│ ├── web-ae9c1fbe71b266e_bg.wasm
│ └── web-ae9c1fbe71b266e.js
├── kabalist_api
├── public
│ └── public_list.html.tera
└── KabaList.toml
You will then need to set the KABALIST_FRONTEND
variable, or frontend
in the KabaList.toml
file to the path of the dist folder (here /opt/kabalist/dist
)
You should put the dist
directory on a server, for example at the location /usr/share/nginx/kabalist
, giving something like:
/usr/share/nginx/kabalist
├── index.html
├── kabalist-d741b2826776e6b4.css
├── web-9a0319286040f46a_bg.wasm
└── web-9a0319286040f46a.js
You will then be able to deploy both the web application and api server on the same domain using nginx, for example:
server {
server_name example.com;
root /usr/share/nginx/kabalist;
location /api {
proxy_pass http://127.0.0.1:8080/;
}
location / {
try_files $uri $uri/ /index.html;
}
listen [::]:80;
listen 80;
}
You should then use something like certbot
to generate a SSL certificate.
By default no users are available, and no registration is possible. In order to create users you will need to use the kb_admin
tool.
You can run kb_admin registration new
to create a registration, and use the link <domain>/register/<id>
, or just go to <domain>
and click register, using the id.
The administration tool can also list registrations & users.