MacroGraph
Log in
GuidesSet up a server

Set up a server

A MacroGraph server runs your project around the clock on your own hardware, such as a home server, NAS, or VPS. You edit it from the browser, and changes apply immediately. All you need is Docker; the image runs on both amd64 and arm64.

  1. Run this on the machine that will host MacroGraph. Docker downloads the image and starts it in the background, restarting it whenever the machine reboots.

    Your project is kept in the macrograph-data volume, so it survives restarts and updates.

    Using Docker Compose instead?

    Save this as compose.yaml and run docker compose up -d.

    services:
  macrograph:
    image: ghcr.io/brendonovich/macrograph-server:beta
    container_name: macrograph
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - macrograph-data:/data

volumes:
  macrograph-data:

  2. The first time it starts, the server prints a one-time setup link to its logs. Open it in your browser.

    If the server is on another machine, use its address instead of localhost, then paste the MACROGRAPH_SETUP_KEY when asked. Setting MACROGRAPH_PUBLIC_ORIGIN makes the printed link use that address.

    Anyone with the link can claim the server, so keep your logs private until you're done. It changes whenever an unclaimed server restarts.

    The account you approve with becomes the server's owner, and the server can use the accounts you've connected to MacroGraph, like Twitch and Discord. You can remove it any time under Account → Apps.

  4. Head back to your server's tab. You're signed in as its owner, and the editor is ready.

Terminal
docker run -d --name macrograph --restart unless-stopped \
  -p 3001:3001 -v macrograph-data:/data \
  ghcr.io/brendonovich/macrograph-server:betaUnable to find image 'ghcr.io/brendonovich/macrograph-server:beta' locallybeta: Pulling from brendonovich/macrograph-serverStatus: Downloaded newer image for ghcr.io/brendonovich/macrograph-server:beta7c2d9e41b8a3f05e6d1c9a8b7e6f5d4c3b2a1908f7e6d5c4b3a29180f7e6d5c4
Step 1 of 4

  1. 1Start the container

    Terminal
    docker run -d --name macrograph --restart unless-stopped \
  -p 3001:3001 -v macrograph-data:/data \
  ghcr.io/brendonovich/macrograph-server:betaUnable to find image 'ghcr.io/brendonovich/macrograph-server:beta' locallybeta: Pulling from brendonovich/macrograph-serverStatus: Downloaded newer image for ghcr.io/brendonovich/macrograph-server:beta7c2d9e41b8a3f05e6d1c9a8b7e6f5d4c3b2a1908f7e6d5c4b3a29180f7e6d5c4

    Run this on the machine that will host MacroGraph. Docker downloads the image and starts it in the background, restarting it whenever the machine reboots.

    Your project is kept in the macrograph-data volume, so it survives restarts and updates.

    Using Docker Compose instead?

    Save this as compose.yaml and run docker compose up -d.

    services:
  macrograph:
    image: ghcr.io/brendonovich/macrograph-server:beta
    container_name: macrograph
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - macrograph-data:/data

volumes:
  macrograph-data:

  2. 2Open your setup link

    Terminal
    docker logs macrographMACROGRAPH_LISTENING 3001MACROGRAPH_SETUP_KEY kD3vQm8Zr1pXw7NcY2tLh5sF0gJb9uAeE4oVi6nRk-c[18:42:07.512] INFO (#3): Open http://localhost:3001/#setup-key=kD3vQm8Zr1pXw7NcY2tLh5sF0gJb9uAeE4oVi6nRk-c to set up this server.[18:42:07.631] INFO (#3): Listening on http://0.0.0.0:3001

    The first time it starts, the server prints a one-time setup link to its logs. Open it in your browser.

    If the server is on another machine, use its address instead of localhost, then paste the MACROGRAPH_SETUP_KEY when asked. Setting MACROGRAPH_PUBLIC_ORIGIN makes the printed link use that address.

    Anyone with the link can claim the server, so keep your logs private until you're done. It changes whenever an unclaimed server restarts.

  3. 3Claim your server

    The account you approve with becomes the server's owner, and the server can use the accounts you've connected to MacroGraph, like Twitch and Discord. You can remove it any time under Account → Apps.

  4. 4Start building

    Head back to your server's tab. You're signed in as its owner, and the editor is ready.

Updating

Pull the latest image and recreate the container with the same volume. Your project and sign-in are kept.

docker pull ghcr.io/brendonovich/macrograph-server:beta
docker rm -f macrograph
docker run -d --name macrograph --restart unless-stopped \
  -p 3001:3001 -v macrograph-data:/data \
  ghcr.io/brendonovich/macrograph-server:beta

With Compose, run docker compose pull then docker compose up -d.

Configuration

Pass these to docker run with -e NAME=value, or under environment in Compose.

MACROGRAPH_PUBLIC_ORIGIN
The address people use to reach the server, such as https://macrograph.example.com. Setup links use it, so set it when the server isn't on localhost.
MACROGRAPH_SERVER_NAME
The name shown when approving the server. Defaults to the container's hostname.
MACROGRAPH_ADMIN_IDS
Comma-separated MacroGraph user IDs that can edit the project, in addition to the owner.
PORT
The port the server listens on inside the container. Defaults to 3001.

Remote access

To reach the server from other devices, put it behind a reverse proxy with HTTPS and set MACROGRAPH_PUBLIC_ORIGIN to its public address. The proxy must forward WebSocket connections.

Backups

Everything the server keeps, including the project, module settings, and who owns the server, lives in /data. Back up the whole volume, and keep it private: it contains sign-in data and module credentials. If you bind-mount a directory instead of using a volume, make it writable by user 1000:1000.