The build infrastructure around Carnap supports two deployment modes: Stack builds for use with the Keter web server on traditional Linux servers and Nix builds for use on Docker or NixOS servers. Stack with Keter is used on Carnap.io. An experimental prebuilt Docker image is available.
If you would like to build Carnap yourself using Nix directly, see the development README.
We provide Nix packaging as the
server attribute returned by
for use in NixOS and NixOps.
If you wish to work with Carnap's Nix infrastructure outside the Docker images, it is highly recommended to use Cachix to avoid having to build anything that our Continuous Integration has already built.
- PostgreSQL database with a user (TODO: which privileges do they need on their database?)
- Writable persistent directory to give as the
- Google API key (see below for information on how to configure it)
Carnap uses a settings file,
settings.yml, to store its configuration. You
can find the example version at
The version in
Carnap-Server/config/settings.yml is bundled within the
executable. To utilize binary caching, Nix builds directly use the example
configuration file, and users are expected to use environment variables or
provide a different YAML file at runtime.
You can provide a different settings file at runtime by passing it as the first
argument to the
Carnap-Server executable. Also, all settings are configurable
by environment variables, which is useful for Docker deployments (see the
example configuration for a list of these settings).
Carnap requires a writable
dataroot, configured with the
environment variable, to store documents and the cookie encryption key in.
This directory can also contain a subdirectory
srv, whose contents are
directly available at
/srv/ on the Carnap instance. This is used for
documentation on the production instance at
For production deployments, Carnap should have access to a PostgreSQL database.
Set the environment variable SQLITE=false and supply
PGHOST, and if required,
PGDATABASE for your postgresql
If you wish to use peer authentication via Unix socket on a locally hosted
PostgreSQL database, set all of
The Carnap team at UBC uses NixOps to automatically deploy Carnap on DigitalOcean servers running NixOS. It's currently experimental and documentation is a work-in-progress, but the configuration files are public.
There is experimental Docker support for Carnap. Images are available via the
GitHub container registry at
Note that Carnap docker images are about 3GB uncompressed and about 500MB to download. This essentially precludes the use of services such as Azure App Service that reload the image on container restart (some tests of Azure App Service have yielded 10+ minute start times).
To run Carnap under docker:
docker run --rm -v carnap_data:/data -e APPROOT=http://your-app-root.com
Two authentication schemes are supported by Carnap, both of which require some configuration. Production Carnap deployments currently require Google authentication to be configured for administration purposes, even if it is not intended to be used by students.
Setting up Google authentication requires setting up a Google APIs project.
First, create the project: https://console.developers.google.com/cloud-resource-manager
Then, create an OAuth2 client ID: https://console.developers.google.com/apis/credentials
It will show up like this:
On the client ID page, set an Authorized Redirect URI for
On your OAuth2 Consent Screen tab, no scopes need to be added as Carnap just needs emails to log in.
Once you've configured all the information on the Google side, fill it in the Carnap configuration file or environment variables:
GOOGLEKEY: your Google Client ID
GOOGLESECRET: your Google Client secret
Go to your newly minted Carnap instance and log in with Google. Then, go to
https://YOURDOMAINHERE/admin_promote and click the button. You will now be
the administrator of this instance. Multiple administrators are supported, but
there is not yet user interface to enable this.
You can manage the site including promoting instructors, managing students, and
configuring LTI platforms at