VDI Service Docker Compose Stack

Table of Contents

• Local Development
  • Quick Start
  • Make Targets
  • Compose Parameters
• License

Local Development

For developer use, this repository includes makefiles with shortcuts for performing the standard docker compose operations, including a full-stack rebuild.

Quick Start

Using Remote App DB

1. Navigate to dev/local-with-remote-appdb/.

2. From that directory run make prep-stack to create a copy of the appropriate stack config file and environment file.
   The stack config copy will be named stack-config.yml.
   The environment file copy will be named .env.

3. Edit the .env file and fill in the APP_DB_* environment variables with the actual target DB details.

4. Follow the ssh-compose section of the util-infra-dev-tools readme to create a docker-compose.ssh.yml file.

5. Run make up to start up the VDI stack.

6. Run make logs to tail the stack logs and ensure the SSH tunnels are successfully established.

Fully Local

1. Navigate to dev/fully-local/.

2. From that directory run make prep-stack to create a copy of the appropriate stack config file and environment file.
   The stack config copy will be named stack-config.yml.
   The environment file copy will be named .env.

3. Run make up to start the VDI stack.

Make Targets

''

Simply running make with no target prints out all the available targets.

Common Targets

prep-stack

Copies the files necessary to run a VDI stack into the working directory that make was called from.

build

Performs a full service stack build from source. This will used cached build layers from the host machine if they are available. Use OPTIONS to change that behavior if desired.

build-db

Builds only the local Postgres App DB image.

up

Runs docker compose up, expecting a .env file in the project root directory by default.

down

Runs docker compose down.

start

Runs docker compose start.

stop

Runs docker compose stop.

restart

Runs docker compose restart.

logs

Runs docker compose logs.

log-service

Runs docker compose logs service, printing out only the logs from the HTTP REST server.

log-{plugin-name}

Prints logs from only the specific target plugin container.

Example

# Show only the biom container logs
make log-biom

cmd

Prints docker compose commands. May be combined with input parameters to generate custom commands to run outside of make.

Compose Parameters

ENV_FILE

Path to the environment file to use with the docker compose command.

Default value is ${PWD}/.env

Example

# runs docker compose top
make compose ENV_FILE="/home/me/my/top/secret/variables.env"

COMPOSE_FILES

Paths to additional docker compose config files that should be included in the compose command.

Example

# adds docker-compose.ssh.yml to the compose file list
make compose COMPOSE_FILES=docker-compose.ssh.yml

COMMAND

Docker compose command to execute.

Default value is dependent on make target, for the compose target, the default value is --help

Example

# runs docker compose top
make compose COMMAND="top"

OPTIONS

Additional CLI options that will be passed to the specific compose command.

Example

# remove volumes as part of the compose down command
make down OPTIONS=-v

SERVICES

Limit the compose command to the provided target services.

Example

# (re)create the wrangler and noop plugin containers
make up SERVICES="plugin-wrangler plugin-noop"

License

Copyright 2025 VEuPathDB

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and limitations under the License.