Upload with MASV Engine in Docker

In this tutorial, you’ll follow the steps your application goes through to send a file with MASV. You’ll use the MASV Engine (formerly MASV Agent) running in a Docker container to upload a single file to a MASV team.

MASV Engine abstracts much of the MASV API for you. It is a fast, reliable, and flexible way to add file transfers to your application. Because your application interacts with MASV Engine via a RESTful web API, you can run it locally, on-premises, or in the cloud.

What you’ll learn

When you’re done, you’ll know how to:

• Set up MASV Engine in Docker
• Authenticate your application
• Start an upload
• Monitor the upload’s progress
• Finalize the upload

Before you begin

You’ll need:

• A MASV account with the Owner or Admin role — sign up here
• A command line shell (this tutorial uses GNU Bash on Linux)
• curl — to interact with the MASV Engine HTTP API
• jq — to format JSON output
• Docker — Docker Desktop or the Docker CLI with Docker Compose
• A file to send (keep it under 1 MB for this tutorial)

Step 1: Set up MASV Engine

Create a folder to run the MASV Engine. The Engine stores data in two Docker volumes:

• config — MASV Engine configuration
• data — uploaded and downloaded files

Create local folders for these volumes before starting the container. If these folders don’t exist, Docker creates them with root as the owner.

mkdir -p send-tutorial/config send-tutorial/data

In your text editor, create the compose.yaml file below and save it in the send-tutorial folder. Replace YOUR-PATH with the full path to your local send-tutorial folder.

services:
  masvengine:
    image: getmasv/masv-engine:3.2.15
    container_name: masv-engine
    # Store your API key in a .env file — never commit it to version control.
    # See /api/api-keys/ for key management best practices.
    environment:
      - TZ=UTC
      - API_KEY=${API_KEY}
    volumes:
      - YOUR-PATH/send-tutorial/config/:/config
      - YOUR-PATH/send-tutorial/data/:/data
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped
    command: ["-api-key", "$API_KEY"]

The compose.yaml uses a Docker environment variable, API_KEY, to authenticate requests to the MASV Engine. You’ll create the API key in the next step.

For full Docker setup details, see the Docker setup guide.

Tip

Your application can also use Docker secrets to pass the API key to the MASV Engine container.

Step 2: Get an API key

To authenticate with the MASV Engine, your application needs an API key.

To create an API key, you must be the MASV account Owner or Admin for a Team.

Caution

Keep the API key secure. It acts like a password that MASV uses to authenticate your requests. Any application that uses this key has the full privileges of your MASV user account.

Store the API key in a file named .env in the send-tutorial folder. Docker Compose uses this file to pass environment variables to the container.

To get an API key:

1. Sign in to the MASV Admin Console as the account Owner or Admin.
2. Follow the steps to create an API key.
3. Create a .env file in the send-tutorial folder with your key:

API_KEY=<YOUR_API_KEY>

Caution

Never commit .env files to version control. Add .env to your .gitignore to prevent accidentally pushing secrets to your repository.

Step 3: Start MASV Engine

Open a new terminal window to start the container (so you can see the MASV Engine log while working in the first terminal):

docker compose up

Tip

If you don’t have permission to run Docker, you may need to add your user to the docker group.

After Docker loads the image and the MASV Engine starts, you’ll see output like this:

masv-engine  | [INFO] 20:47:22: Backend: https://api.massive.app
masv-engine  | [INFO] 20:47:22: API Server listening on [::]:8080

Confirm that the MASV Engine has started a session:

curl --head --request GET http://localhost:8080/api/v1/login

A successful response:

HTTP/1.1 200 OK
Content-Type: application/json

If you receive a 401 Unauthorized response, your API key was not accepted. Create a new key, update the .env file, and restart the container.

Step 4: Get your Team ID

You need a Team ID to specify which MASV Team to upload to. The teams endpoint returns a JSON array of Team objects:

curl --silent --request GET http://localhost:8080/api/v1/teams | jq '.[] | { name, id }'

Example response:

{
  "name": "First Unit Team",
  "id": "0EGXTA6M1PNLGEV2DJ53FJKGBD"
}
{
  "name": "Second Unit Team",
  "id": "E1XNAZMFP8LDEJ1HKTW5EBAVNM"
}

Choose a Team and save its id in a shell variable:

TEAM_ID="0EGXTA6M1PNLGEV2DJ53FJKGBD"  # replace with your Team ID from the response above

Step 5: Start the upload

A MASV Package is like a virtual folder inside MASV. From the end user’s point of view, a package contains all the files and folders of a single transfer.

The Docker volume for /data contains the files that MASV Engine uploads and downloads. Copy your file into the data folder:

FILE=cat.jpg
cp /path/to/your/"$FILE" send-tutorial/data

Now start the upload. Your application provides the Team ID, file paths (absolute paths starting with the container’s /data folder), and a package name and description:

curl --silent --request POST \
  -H "Content-Type: application/json" \
  http://localhost:8080/api/v1/uploads -d "{ \
  \"team_id\":\"$TEAM_ID\", \
  \"paths\":[\"/data/$FILE\"], \
  \"package_name\": \"My first package\", \
  \"package_description\": \"A cat in a package\" \
}" | jq

MASV Engine starts uploading immediately in the background and returns:

{
  "package_id": "01ENXTA4MFP1LWEXEDKQK7XKV",
  "upload_id": "ccea8dc3-3af3-4e0e-b8f0-8cf23d9968e7"
}

• package_id — unique ID for the package that MASV Engine created
• upload_id — unique ID for tracking and managing the upload

Save the upload ID:

UPLOAD_ID="ccea8dc3-3af3-4e0e-b8f0-8cf23d9968e7"  # replace with the upload_id from the response above

For full details on upload types and options, see the MASV Engine Uploads guide.

Step 6: Track progress

Use the upload ID to poll the MASV Engine for progress. Poll no more frequently than every 5 seconds.

curl --request GET http://localhost:8080/api/v1/uploads/$UPLOAD_ID | jq

Example response (shortened):

{
  "items": [ "..." ],
  "name": "My first package",
  "progress": 417216,
  "size": 417216,
  "state": "idle",
  "package_name": "My first package",
  "package_id": "01ENXTA4MFP1LWEXEDKQK7XKV",
  "upload_id": "ccea8dc3-3af3-4e0e-b8f0-8cf23d9968e7"
}

Key properties:

• items — array of files in the package with individual progress details
• progress and size — bytes uploaded so far and total package size
• state — current upload status

Step 7: Finalize the upload

After the MASV Engine finishes uploading and the state is idle, finalize the package. Finalizing lets MASV know the package is ready — MASV can then notify recipients, save to cloud integrations, and process any configured automations.

curl --silent --request POST http://localhost:8080/api/v1/uploads/$UPLOAD_ID/finalize | jq

Response:

{
  "code": 200
}

Your package is ready

Your application has authenticated, created a package, uploaded a file, and finalized the upload. The package is now available for download in the MASV Admin Console.

Next steps

• MASV Engine — Full details about adding MASV transfers and automations to your application.
• MASV Engine Docker Setup — Complete Docker configuration reference.
• MASV Engine Uploads — All upload types with CLI and REST API examples.
• MASV Web Uploader — A browser-based uploader SDK for web applications.
• MASV API — The RESTful API for interacting directly with the MASV cloud.