Docker setup

Supported architectures

MASV Agent supports multiple architectures to allow for deployment in various environments.

Specify the masvio/masv-agent:latest image to automatically pull the correct architecture for your system.

The architectures supported by this image are:

Architecture	Tag
x86-64	latest
arm64	latest

MASV Agent setup with Docker

1. Ensure that Docker is installed on the host machine where the MASV Agent container will run.
2. Pull the MASV Agent Docker image:

   docker pull masvio/masv-agent:latest
   

3. On the Docker host, create directories to store MASV Agent config files and for sending and receiving files:

   mkdir ~/masv-agent
   mkdir ~/masv-files
   

   You'll use these paths in later steps to map to Docker volumes for the MASV Agent's container. Feel free to change these to any other paths you prefer.

4. Run the Docker container with the MASV Agent server:

   Docker CLIDocker Compose

   docker run -d \
   --name masv-agent \
   -u 1000:1000 \
   -v ~/masv-agent:/config \
   -v ~/masv-files:/data \
   --restart unless-stopped \
   masvio/masv-agent:latest
   

   To authenticate with a docker-compose file, define a Docker environment variable or Docker secret. This example uses an environment variable, API_KEY to pass to the MASV Agent command line:

   compose.yaml

   version: "3"
   services:
     masvagent:
       image: masvio/masv-agent:latest
       container_name: masv-agent
       user: "1000:1000"
       environment:
         - TZ=UTC
         - API_KEY=${API_KEY}
       volumes:
         - ~/masv-agent:/config
         - ~/masv-files:/data
       ports:
         - 8080:8080
       restart: unless-stopped
       command: ["--api-key", "$API_KEY"]
   

   Then run the container with:

   docker-compose up
   

   • The ~/masv-files:/data volume maps the host's ~/masv-files directory to the container's /data directory, which is important for adding a storage gateway connection later.
   • Replace -u 1000:1000 with the corresponding user/group ID’s that MASV Agent will be running as. Depending on your configuration, this might or might not be necessary.
   • The ~/masv-agent:/config volume maps the MASV Agent config directory to the host's ~/masv-agent. MASV Agent uses this directory to store configuration and transfer states. It’s important to keep this data intact in order to maintain transfer progress between restarts.

Volumes

MASV Agent stores configuration, and uploaded and downloaded files, in a couple of folders. You can override them if required, but we recommend keeping the defaults. To make these container folders persistent, use Docker volumes.

Volume	Usage
/config	Store application configuration and saved application data
/data	Default folder to mount in your automated downloads and uploads

Tip

Create matching folders on the Docker host before starting the container. Otherwise, Docker creates these folders with root as owner.

Parameters

When launching the MASV Agent with masv server start, we can configure it using various command-line flags. See the full list here

Executing MASV Agent commands

You must add docker exec masv-agent before a masv command to execute it within the container. For example, you can list storage gateway connections with:

docker exec masv-agent masv gateway ls

As a convenience, you might want to set up an alias for the whole command to streamline interactions on the terminal:

alias masv='docker exec masv-agent masv'

masv gateway ls

Alternatively, you can also exec into an interactive shell environment within the container:

docker exec -i masv-agent bash
$ masv gateway ls

Next steps

• Downloads: Start, monitor, and manage downloads with the MASV Agent.
• Uploads: Start, monitor, and manage uploads with the MASV Agent.
• Storage Gateway: Set up secure remote access to your physical storage.