4.4 KiB
basebox Sample: TODO App
This project implements the Hello World of API-driven apps: a simple TODO app, built with Vue 3.
The bbconf folder contains basebox config files, GraphQL schema, precompiled database schema, type maps etc. and scripts to run broker and dbproxy from within the bbconf directory.
These files assume that you extracted the basebox distribution next to this repository's root.
Example:
Let's assume you create a basebox folder in your home directory, change into it, extract the basebox distribution archive in that folder and then clone the contents of this repository into the same folder:
cd ~
mkdir basebox
cd basebox
tar xzf basebox-x.x.x.tgz # adopt this command to the archive you downloaded
git clone --single-branch --depth 1 https://gitea.basebox.health/samples/vue-todo.git
The basebox archive will be extracted into a directory named basebox-<version>; for the scripts in vue-todo/bbconf to find the basebox binaries, please create a symbolic link to the basebox directory named basebox, e.g.
ln -s basebox-x.x.x basebox
If you follow these steps, the scripts in bbconf will work out of the box.
Installation
To install this app, you need
- npm, node.js
- A PostgreSQL server
- basebox (broker, dbproxy, bbc extracted from the basebox archive)
- Keycloak or Auth0
PostgreSQL Preparation
You need a PostgreSQL database to run this app. You can read detailed instructions on how to install PostgreSQL and create a test database at our PostgreSQL Primer page.
Let's create a PostgreSQL user and database for the TODO app:
# Under (Debian) Linux, switch to the postgres user first:
# sudo su postgres
createuser -DRP bb_todo # default password: basebox
createdb -O bb_todo bb_todo
If you use a different password than basebox, you also have to change bbconf/dbproxy-config.toml accordingly.
Tell PostgreSQL that the bb_todo user connects to the database using md5 authentication. To do so, edit /etc/postgresql/<PostgreSQL version>/main/pg_hba.conf (on Debian based Linux systems) to contain the following:
# TYPE DATABASE USER ADDRESS METHOD
local bb_todo bb_todo md5
Make sure to add the line that starts with local bb_todo... under the commented header that starts with # TYPE.... PostgreSQL uses the first line that matches, so having the new line on top makes sure no other line overrides it.
Reload PostgreSQL config:
sudo systemctl reload postgresql
Database Schema
This repository contains an already compiled SQL file that creates the database schema:
psql -U bb_todo bb_todo < bbconf/bb_todo-datamodel.sql # Enter password when prompted.
The database configuration and installation is now complete.
If you're curious, you can recompile the GraphQL schema like so:
basebox/bin/bbc --prefix=bb_todo -f vue-todo/bbconf/todo_schema.graphql -o vue-todo/bbconf
Client Installation
After installing node.js and npm, open a terminal window, go to the root of the vue-todo repository and enter the following commands:
cd vue-todo
npm i
This will install the client app's dependencies.
OpenID Connect
You can setup and use your own OpenID Connect server; if you do so, you also have to update the config files bbconf/broker-config.toml and bbconf/dbroxy-config.toml accordingly.
Run
Start dbproxy
Open a new terminal window, then:
cd ~/basebox/vue-todo/bbconf
./dbproxy.sh
This command starts dbproxy; you will see a lot of log messages being written to the console.
Start broker
Open another terminal window, then:
cd ~/basebox/vue-todo/bbconf
./broker.sh
Again, you see broker's log messages on the console. Each request to the broker will be shown, similar to an Apache or nginx access log.
Start the Client
In another terminal window:
cd ~/basebox/vue-todo
npm run dev
This will start a node.js based HTTP test server that will host the client application. It will print the URL where you can load it to the console:
VITE v4.1.4 ready in 273 ms
➜ Local: http://localhost:5173/
➜ Network: use --host to expose
➜ press h to show help
Open your browser, go go the URL in the npm console, and enjoy.