Licensed to be used in conjunction with basebox, only.
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.
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
If you use a different OpenID Connect provider system, we would be happy to hear from you should you encounter problems or succeed.
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.
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.
The archive file you downloaded contains the following items:
basebox README file
basebox change log
directory with executables; contains bbc, broker and dbproxy
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.
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
GraphQL Schema Compilation
Create a directory for the configuration of your test project:
Then compile your schema:
If everything goes well, you get 3 files in the
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
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:
If you have no PostgreSQL database or need more details on how to do this, please refer to our quick PostgreSQL Primer.
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:
dbproxy is our secure database proxy server. It is configured, like broker, with a single config TOML file you can use as a starter:
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 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.