Venue Quick Start
As a user you can work with the Covia Grid through the online web app or the SDK alone. But for more powerful capabilities, such as controlling local resources and installing custom adapters, you may want to create your own venue.
A venue is implemented as a server process that you can run by obtaining covia.jar from the latest release on GitHub (see Release channels below for the options).
Running a venue requires Java 21+ installed. The venue can be launched with:
java -jar covia.jar
This will launch a local venue with a default configuration, suitable for testing and development. You can connect to it with the Covia web app at http://localhost:8080.
To configure the venue, pass a JSON5 config file (java -jar covia.jar config.json); see the Configuration Reference for all keys.
Each venue also includes a web presence for diagnostics and discovery of server capabilities. This will appear at http://localhost:8080 — the same URL you use to connect from the Covia app. For an example of this website, see the hosted Test Venue.
With Docker
A published container image is available if you'd rather not install Java (the image ships its own Java runtime, currently the latest LTS):
docker run -p 8080:8080 ghcr.io/covia-ai/covia:stable
Mount a volume and point store at it (see Configuring the Venue) to persist state across container restarts.
Release channels
Pick the channel that matches how much churn you want:
| Channel | JAR | Docker image | Built from |
|---|---|---|---|
| Release (recommended) | latest or a versioned release | :stable, or pinned :0.2.0 | master, versioned releases |
| Development | latest-snapshot | :latest | every push to develop |
The hosted example venues follow the same channels: venue-1 and venue-2 (Google Cloud) run the release channel, while venue-3 (AWS) and venue-4 (Azure) redeploy automatically from the development channel.
For production, pin a specific version (a release tag for the JAR, :0.2.0-style image tags for Docker) and upgrade deliberately. The development channel tracks develop and may change under you — it's the right choice only if you're following new features or contributing. See the CHANGELOG for what each release contains.
Building the venue server
The venue server is a Maven project in Java.
You can build it with Maven 3.5+ using the following command in a clone of the Covia repo root directory:
mvn clean install
This will build the project, including the full venue .jar at venue/target/covia.jar.
Configuring the Venue
A venue can be configured with a JSON / JSON5 config file to enable or disable features, add adapters, and more. Pass the config file path as the first argument when launching:
java -jar covia.jar my-config.json
With no config file, the venue starts with a built-in local-test configuration.
An example configuration file is available as a documented template.
By default a venue with no store configured keeps state in an ephemeral temporary store that is wiped on exit. For a venue you intend to keep, set store to a file path — see Persistence for the durability model, and Authentication for locking down access. The repository's deploy/ directory contains cloud provisioning examples (e.g. an Azure VM setup and deploy workflow) you can adapt.