All in One Container

Features

The following are the various features for running the All in One Container. The container will always contain the complete WWWHerd application, but WWWHerd itself is designed to be a cloud native application. As such, the container has a lot of components in it. We will always be certain you can run it on a mid-tier laptop.

Note that there are convenient scripts that cover some of the features. They are covered below as well

Import a database file

In the Quick Start section, this was done manually in the UI. You can pass an environment variable to the container that will import database files. The following replicates what was done in the Quick Start.

docker run -p80:80 -p8888:8888 -v /build/wwwherd/integration/demo:/demo -e WWWHERD_IMPORT='1:/demo/wwwherd_demo.json' -d wwwherd/all:latest

Important: This assumes you run this command from the root of the WWWherd repository. To get the repository, run the following:

git clone https://gitlab.com/ginfra/wwwherd.git
cd wwwherd

If you don't have git installed, look at the instructions here.

The environment variable that causes the import is WWWHERD_IMPORT. The variable format is as follows:

WWWHERD_IMPORT=orgid:filepath

Multiple imports can be added by making them comma separated. Be sure to include the orgid: part for all of them. Only org 1 (default) can import into other organizations.

WWWHERD_IMPORT=orgid:filepath,orgid:filepath

OrgId '1' is the default organization and will always be present.

Set up providers

Providers can be set up during container startup by setting the environment variable WWWHERD_PROVIDERS. If any provider already exists, it will be updated.

the variable will be as follows:

WWWHERD_PROVIDERS=orgid:name:type:(optional)url:(optional)model:key

The optional items can be empty strings. More than one provider can be added by making them comma separated.

Types are as follows (use the value, not the name):

name: 'Anthropic', value: 1
name: 'OpenRouter', value: 2
name: 'Self Hosted', value: 3

The following is an example of how to start the container:

docker run -p80:80 -p8888:8888 -e WWWHERD_PROVIDERS='1:anthropic:1:::sk-ant-api03-giYDiE-XWj6...' -d wwwherd/all:latest

This along with the previous feature are intended to enable CI for WWWHerd itself. WWWHERD_IMPORT will always be done before WWWHERD_PROVIDERS.

Running with TLS/SSL.

To run with SSL, you need to mount a volume to /wwwherd/import inside the container. The volume must container two files--server.key and server.cert. These are your SSL key and certificate. Self-signed will work ok, but your browser will nag you (rightfully) that it isn't secure.

For reference, these two files will be mapped to the following NGinX configuration:

        ssl_certificate /wwwherd/import/server.cert;
        ssl_certificate_key /wwwherd/import/server.key;

The following is an example of how to run the container:

docker run -p80:80 -p8888:8888 -v ~/keys:/wwwherd/import -d wwwherd/all:latest

Assuming that directory ~/keys has the two files mentioned above. The URL will change to the HTTPS port, such as https://localhost. The test app will not change.

Encrypting API keys in the database.

You can make sure the API keys (i.e. Anthropic, OpenRouter) are encrypted in the database by adding the environment variable KEY_CRYPTO to the container.

The following is an example of how to run the container:

docker run -p80:80 -p8888:8888 -e KEY_CRYPTO='Your crypto key' -d wwwherd/all:latest

It doesn't actually matter what your key is as long as it is sufficiently long and random, and you won't use it outside of setting the environment variable. While I make no guarantees and you should do your own research, a common way to do this is with the following command:

openssl rand -base64 32

Sending data to OpenTelemetry collector.

To send data to an OpenTelemetry collector, simply add the environment variable "OTELENDPOINT" to the docker run command.

The following is an example of how to run the container:

docker run -p80:80 -p8888:8888 -e OTELENDPOINT='grpc://191.168.1.41:4317/' -d wwwherd/all:latest

GRPC transport is tested and supported. HTTP has been implemented, but it is not regularly tested and thus not directly supported. (Contact us if you have an urgent need for it.)

Convenience Scripts

All scripts are in the bin/ directory and should be run from the repo root directory.

To start a clean instance, run the following:

bin/start_all.sh

To start a clean instance with TLS, run the following. The keys must be present in the current working directory.

bin/start_all_tls.sh

To start an instance with the Demo data, run the following.

bin/start_container_test.sh

To start an instance with the BAT (Basic Acceptance Test) data, run the following. The BAT has a lot of good examples of how to use WWWHerd:

bin/start_container_bat.sh

To start an instance with the CI data, which is an extension of the BAT, run the following.

bin/start_container_ci.sh