Install Zetaris locally

This guide covers a local Docker Compose installation. The local path was tested on a fresh install; see the test record. For a managed compute cluster in your AWS account, use Managed AWS cluster.

1. Obtain the distribution and access

What is being installed

The bundle includes:

Download and licensing

You need the platform archive, its matching .env, registry credentials and a Zetaris licence or evaluation entitlement covering your installation.

1. Start at Zetaris Cloud for a local installation. Choose Start Free to open the account portal, then register or sign in with your existing account. You can also use the registration page directly. Your Zetaris Cloud credentials are separate from the administrator account you will create inside your installation.
2. Review the Terms and Conditions and Privacy Policy before completing registration. Your use of the platform is governed by your Order with Zetaris. Without one, the agreement allows internal evaluation for up to 30 days; it does not grant an ongoing licence.
3. Open the Run locally page, download zetaris-platform.zip and use the registry sign-in command supplied there. That page also has the current local startup steps and sign-in details. Move the zip out of Downloads before unpacking it. If the download is not available for your account, contact Zetaris Support to have it enabled.

If your organisation has already arranged access, use the supplied archive and registry credentials. The Apache licence in the getting-started repository covers the data recipes only, not the platform images.

The getting-started repository contains recipes and guides, not the platform images. Keep the supplied bundle files together and use its matching .env. Some older bundle comments refer to .env.example or env/make-env.sh; those files are absent from this distribution. Ask the distributor for a matching .env if it is missing, and keep the supplied image references as a set.

2. Local Docker Compose

2.1 Prepare the machine

Install Docker Desktop on macOS/Windows, or Docker Engine with the Compose plugin on Linux. On Windows, run the shell commands from WSL2 with Docker Desktop integration enabled.

On Docker Desktop, the memory allocation to Docker matters, not just the laptop's installed RAM. Leave headroom for the operating system and other applications. On Apple Silicon, enable supported amd64 acceleration where available and allow extra startup time.

2.2 Extract the bundle and authenticate

From the directory containing the downloaded archive:

unzip zetaris-platform.zip
cd zetaris-platform
docker version
docker compose version
docker login zetarishackathon.azurecr.io
./preflight.sh

Enter the registry credentials issued by Zetaris at the prompts. Run subsequent platform commands from this directory, which contains docker-compose.yml.

Resolve every preflight failure before proceeding. The registry check detects a stored login configuration; docker compose pull is the definitive check that the credentials can access the required images. Check free space in Docker Desktop's disk image as well as on the host.

2.3 Configure before first startup

Edit the supplied .env in an editor. Keep the issued image settings and other supplied values. Set or confirm:

The administrator password must be at least eight characters and contain lowercase, uppercase, a digit and one of $ @ ! % * ? &. Other punctuation is rejected.

Keep .env private and out of version control:

chmod 600 .env
docker compose config --quiet

--quiet validates the configuration without printing resolved secrets.

2.4 Pull and start

docker compose pull
docker compose up -d
docker compose ps --all

Image downloads and first startup can take time, especially on Apple Silicon. Use service readiness rather than elapsed time to decide when startup is complete.

docker compose logs --tail=80 driver api bootstrap
./verify.sh

Expected results:

• postgres, driver, api, ui and ai-datasteward are running; check their health in docker compose ps --all.
• init and bootstrap show Exited (0). They are successful one-time setup jobs.
• verify.sh passes all nine checks, including login and a query through the UI, API and query engine.

If bootstrap is still running, wait for it to finish and rerun the verifier. If ui checks fail immediately after bootstrap finishes, wait a minute and run ./verify.sh again before troubleshooting. Continue with section 3.

3. First login and initial verification

1. Open http://localhost:3000.
2. Sign in with the administrator email and password configured before bootstrap.
3. Open the SQL Editor and run:

SELECT 1 AS one;

Expect one row with value 1. This confirms that an authenticated query reaches the engine without depending on an external dataset.

If you use a shipped default password, change it immediately.

Changing ZETARIS_ADMIN_PASSWORD or the organisation in .env after bootstrap does not recreate or reset existing accounts. After a UI password change, the verifier needs a matching credential value in .env; otherwise its login check can fail even though the services are healthy.

4. Next steps

In the SQL Editor, start with the supplied sample SQL. When you are ready to connect another source, choose a Cookbook.

5. Stop and tear down

Run from the platform directory:

docker compose stop          # stop containers, retaining data
docker compose start         # resume stopped containers
docker compose down          # remove containers/network, retain named volumes
docker compose up -d         # recreate containers using retained data

docker compose down -v also deletes the named volumes, including the metastore and encryption keys. Use it only when discarding the installation.

Use the getting-started repository at https://github.com/zetaris/getting-started/tree/44668b267ad7ee0fae25ce7588e9620121d47cae as the workspace. If it is not checked out, help me clone and open it first. Read docs/connections/client-setup.md for setup. Keep credentials in .env.local, never in this prompt or a report.

Read AGENTS.md and follow it. Run python3 scripts/preflight.py --jdbc and show
me the result. Report JDBC and REST checks separately. Stop on JDBC failures and report
what is missing. REST failures alone do not block JDBC. If the driver JAR path is not set, ask me
for it. Once readiness checks pass, connect over JDBC to the instance
configured in .env.local and confirm with SELECT 1 and SHOW LIGHTNING DATABASES.

If a local port check returns `Operation not permitted`, retry the same
read-only check with approved network access before reporting the endpoint as
closed. Distinguish missing Python runner dependencies (`.venv` or
`jaydebeapi`) from direct Java JDBC readiness; do not install dependencies
without asking.

Goal: verify SQL execution, inspect the supplied NY_TAXI and TPCDS_DB tables, then run a sample SELECT with LIMIT 5. Do not create objects.

Dry-run before creating anything and wait for my go-ahead.