Getting Started

This guide walks you through setting up a CloudPulse server agent on your machine using Docker. Once running, the agent connects to the CloudPulse dashboard so you can manage your files remotely.

Prerequisites

  • •Docker and Docker Compose installed on the machine that will serve your files.
  • •A CloudPulse account. Create one here if you haven't already.

1. Register a server

Go to Settings → Manage Servers and add a new server. Give it a name you'll recognise (e.g. “Home NAS” or “Raspberry Pi”).

After registering, you'll be shown a Server ID and API Key. Copy them somewhere safe — the API key is only displayed once.

2. Create a docker-compose.yml

On the machine you want to serve files from, create a docker-compose.yml file with the following contents:

docker-compose.yml
services:
  cloudpulse:
    image: cloudpulse-server
    restart: unless-stopped
    network_mode: host
    environment:
      CLOUD_URL: https://cloudpulse.duckdns.org
      SERVER_ID: your-server-id
      API_KEY: your-api-key
      ROOT_DIR: /data
      PORT: 4000
    volumes:
      - /path/to/your/files:/data

3. Configure the environment

Replace the placeholder values with your own:

SERVER_ID

The server ID you received when you registered the server.

API_KEY

The API key shown once after registration. This authenticates your server with CloudPulse.

CLOUD_URL

The URL of your CloudPulse dashboard. If you're using the hosted version, leave it as-is.

ROOT_DIR

The path inside the container that maps to your files. Leave as /data and configure the volume mount instead.

PORT

The port the server agent listens on. Defaults to 4000.

volumes — /path/to/your/files:/data

Replace /path/to/your/files with the directory on your host machine you want to expose through CloudPulse.

4. Start the server

From the directory containing your docker-compose.yml, run:

docker compose up -d

The agent will start, register itself with CloudPulse, and begin sending heartbeats. Within a minute your server should appear as online in the dashboard.

5. Browse your files

Head to the Dashboard, click on your server, and you'll see the contents of the directory you mounted. From here you can upload, download, create folders, move, and delete files.

Notes

  • •The compose file uses network_mode: host so the agent can be reached on your LAN without port-mapping issues. If you need bridge networking, remove this line and add a ports mapping instead.
  • •The server sends a heartbeat every 60 seconds. If the dashboard shows your server as offline, check that the container is running with docker compose logs -f.
  • •To update to the latest image, run docker compose pull && docker compose up -d.