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

Updating MASV Agent

It's important to follow the steps below when updating the MASV Agent. The filesystem changes within a docker container are not easily migrated to a new container. For this reason, we recommend that you store your configuration files in an external, persistent host directory and map to the directory.

1. Stop the current version of the MASV Agent container.
2. Make a copy of the existing MASV Agent config directory and save it to a safe place. It contains configuration, transfer records, and any custom files, such as scripts.
3. Pull the image of the new MASV Agent.
4. When setting up the config location for the new container, do one of the following:
   • Point to the old config directory.
   • Set up a new config directory and paste the old config directory files into the new location.
5. Finalize the new container.
6. Run the new container to ensure it is working as expected and records have been updated correctly.
7. Delete the old container.

Note

You can use the old config directory to reinstall the previous version of the MASV Agent if there are ever any issues with an update. You can delete the copy of the old config directory when you no longer need it.

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.