Skip to content
Copyright © 2022- basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

basebox Installation

This document describes how to get version 1.0.0 of basebox up and running in the simplest possible way, based on Docker. Later, we will add a section about how to deploy basebox in a production environment.

System Requirements

To give basebox a try, you first need to install Docker Compose; you find instructions for its installation here. basebox components run within several Docker containers. You would also need an Identity Provider (IdP) which manages authentication and authorization. You can use Auth0 for a starter; they have a free plan to get you going quickly. Or you use your own Keycloak server

OpenID Connect

basebox relies on OpenID Connect for authorization and authentication. So far, we have tested Auth0 and Keycloak.

If you use a different OpenID Connect provider system, we would be happy to hear from you should you encounter problems or succeed.

Example Application

We provide an example application, a simple TODO-app written in Vue, to help you get started; check out its git repository at https://gitea.basebox.health/samples/vue-todo.

Its README.md file contains all information to get it running quickly.

We have included a Docker container with a configured working version of this application with the download of basebox, this is to assist you in getting up and running as quickly as possible.

Download

Get the basebox distribution for your platform at basebox.io/download. We bundle the lastest version in Docker containers, if you would like the executables to run on either bare metal servers or on different containerization software, please let us know here.

Extract Archive

The archive file you downloaded contains the following items:

README.md

basebox README file

CHANGES.md

basebox change log

bin

directory with executables; contains bbc, broker and dbproxy

Note

The following commands assume that you are in a terminal window with the current directory at the root of the basebox archive you just extracted.

We also assume a project name of bbtest, so whenever you see "bbtest" please substitute with your project's name.

Database

The first step after extraction of the archive is to configure the database. You have to provide a GraphQL schema file with simple annotations that tell basebox how your data types are related to each other. See the documentation of bbc, the basebox compiler, for further details.

Of course, you can also take a look at the schema for the example todo app; see the file todo_schema.graphql in example/bbconf.

GraphQL Schema Compilation

Create a directory for the configuration of your test project:

mkdir bbconf

Then compile your schema:

bin/bbc --prefix=bbtest -o bbconf <path/to/your/graphql/schema.graphql>

If everything goes well, you get 3 files in the bbconf directory:

  • bbtest-datamodel.sql - the SQL script you use to initialize your database
  • bbtest-resolver.toml - a resolver file used by basebox to handle your requests
  • bbtest-typemap.json - typemap, also used by basebox internally

PostgreSQL Database

Create a database and possibly a dedicated user for your project and initialize the database with the SQL script generated during the compilation step above:

sudo -u postgres -c psql bbtest < bbconf/bbtest-datamodel.sql

If you have no PostgreSQL database or need more details on how to do this, please refer to our quick PostgreSQL Primer.

basebox Binaries

broker

broker is basebox' HTTPS GraphQL server. Your client sends GraphQL requests to the broker. For more information about what the broker is and how to configure it, see the broker guide.

In a nutshell, create a configuration file using the default as a template: 

bin/broker -d > bbconf/broker-conf.toml

Edit the file bbconf/broker-conf.toml to suit your needs; refer to the broker guide or reference for details on the configuration file.

dbproxy

dbproxy is our secure database proxy server. It is configured, like broker, with a single config TOML file you can use as a starter: 

bin/dbproxy -d > bbconf/dbproxyr-conf.toml

The dbproxy config file is described in the dbproxy guide and reference.

Your Client

Whatever your client may be, it just has to be able to send GraphQL requests and provide a valid access token; see OpenID Connect login flow.

Post your GraphQL requests to https://broker.tld/graphql - where "broker.tld" is the host name or IP address of the machine where broker is running.

User Management

User management is done entirely in your OpenID Connect provider system, e.g. Keycloak. When you create a new user, the database controlled by basebox does not learn about the new user automatically. You have to send an explicit create user mutation; how this may look depends on your schema. For an example, see the TODO example application; it creates the user in its storeInit() function in store.js.