doceventio/filerouter repository overview

⁠DocEvent filerouter

filerouter is a small, self-contained agent you run on your own machine to move files between a local directory and your DocEvent⁠ channels. It is the on-premise edge agent for the DocEvent channel pipeline — think of it as a managed, resumable replacement for hand-rolled cron + curl/FTP scripts.

• Send — watch a local directory and deliver new files to a DocEvent channel.
• Receive — pull files off a channel and land them in a local directory.
• Both — run any number of send and receive routers from one config file.

It talks to DocEvent purely over HTTPS (outbound only — no inbound ports to open). Delivery is at-least-once with de-duplication, survives restarts, and optionally applies PGP encryption/decryption at the edge.

⁠Supported tags

Architectures: linux/amd64, linux/arm, linux/arm64. The image runs as a non-root user and contains only the filerouter binary plus CA certificates and tzdata.

⁠Quick start

The image ships only the binary. At runtime you mount your config and bind-mount every directory a router reads from or writes to. The paths inside the config must be the container paths you map to.

1. Create filerouter.yaml (a receive example — pull files off a channel to disk). Get the <region>/<endpoint-id> and api-key from the Channels → Downloads area of the DocEvent console⁠:

domain: docevent.io

routers:
  # RECV: DocEvent channel -> local disk
  recv-invoices:
    source: ap-southeast-2/1122334455667788   # <region>/<endpoint-id>
    api-key: REPLACE_WITH_ENDPOINT_API_KEY
    destination: /data/incoming               # a path INSIDE the container
    tmp-directory: /data/incoming/tmp         # same filesystem for atomic rename
    on-collision: overwrite                   # overwrite | skip | rename

2. Run it, mapping the container destination to a host directory:

docker run -d --name filerouter \
  -v /path/to/filerouter.yaml:/etc/filerouter/filerouter.yaml:ro \
  -v /srv/docevent/incoming:/data/incoming \
  doceventio/filerouter:latest

Files landing on the channel now appear in /srv/docevent/incoming on the host.

⁠Sending files to a channel

For a send router, point source at a directory you bind-mount, and the filerouter uploads new files as they stabilise:

routers:
  send-orders:
    source: /data/outgoing                    # watched directory (container path)
    destination: ap-southeast-2/8f3c1e90ab7d4a21
    api-key: REPLACE_WITH_ENDPOINT_API_KEY
    match-extension: .xml                      # optional filter
    match-stability: 5                         # seconds unchanged before pickup
    post-send-delete: true                     # delete after the channel acks

docker run -d --name filerouter \
  -v /path/to/filerouter.yaml:/etc/filerouter/filerouter.yaml:ro \
  -v /srv/docevent/outgoing:/data/outgoing \
  doceventio/filerouter:latest

You can define send and receive routers in the same file and bind-mount all of their directories in one docker run.

⁠Configuration notes

• One file, both directions. Each entry under routers: is one direction, inferred from which side is a local path and which is a <region>/<id> endpoint.
• The api-key is a secret. It is the same credential your DocEvent endpoint uses. Keep filerouter.yaml readable only by you (chmod 0600) — the filerouter warns on startup if it is group/world-readable.
• Atomic landing. Received files are written to tmp-directory and renamed into place, so consumers never see partial files. Keep tmp-directory on the same filesystem as destination.
• PGP (optional). Add a pgp: block to a router to encrypt on send or decrypt on receive at the edge (standard OpenPGP, interoperable with GnuPG).

Default container command:

run -c /etc/filerouter/filerouter.yaml

Override it to use other subcommands, e.g. validate your setup:

docker run --rm \
  -v /path/to/filerouter.yaml:/etc/filerouter/filerouter.yaml:ro \
  doceventio/filerouter:latest doctor

⁠Security

• Outbound HTTPS/TLS on every hop; no inbound ports required.
• Runs as a non-root user inside the container.
• api-keys live only in your mounted config; nothing sensitive is written to logs.
• Fail-closed on an unreachable channel, checksum mismatch, or PGP failure.

⁠Documentation & support

• Console: https://console.docevent.io⁠ (Channels → Downloads)
• Support & guides: https://support.docevent.io⁠
• Standalone binaries (macOS / Linux / Windows) are available from the console Downloads page if you prefer not to use Docker.

Questions or issues? Contact [email protected]⁠.