Skip to content

Bare metal

The preferred way to run PutFS. No Docker overhead, direct filesystem access, systemd process management. The python dependencies for the API are minimal and can be installed on any system.

Example file layout

/opt/putfs/venv/          Python venv with putfs + granian
/srv/putfs/               Data root (or ZFS mountpoint)
/etc/putfs/keys.conf      API keys (nginx map format)
/run/putfs/putfs.sock     Unix socket (created by granian)
/etc/systemd/system/putfs.service
/etc/nginx/sites-available/putfs

Setup

Install

python3 -m venv /opt/putfs/venv
/opt/putfs/venv/bin/pip install putfs

Create data directory

mkdir -p /srv/putfs
chown putfs:putfs /srv/putfs

For ZFS:

zfs create tank/putfs
zfs set mountpoint=/srv/putfs tank/putfs
chown putfs:putfs /srv/putfs

Keys

/etc/putfs/keys.conf

map "$http_x_api_key:$http_x_api_secret" $key_ok {
    default 0;
    "PUTFS_CHANGEME:CHANGEME" 1;
}
map "$http_x_api_key:$request_method:$request_uri" $auth_ok {
    default 0;
    "~^PUTFS_CHANGEME:[^:]+:/.+" 1;
}

See Auth for key scoping.

Systemd service

Copy contrib/putfs.service to /etc/systemd/system/:

cp contrib/putfs.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now putfs

All granian settings are configured via Environment= directives. Override by editing the service file or using a drop-in:

systemctl edit putfs

[Service]
Environment=GRANIAN_WORKERS=8
Environment=PUTFS_ROOT=/tank/putfs

Nginx

Copy contrib/putfs.nginx.conf to /etc/nginx/sites-available/putfs:

cp contrib/putfs.nginx.conf /etc/nginx/sites-available/putfs
ln -s /etc/nginx/sites-available/putfs /etc/nginx/sites-enabled/
# Edit server_name, root path, key file path
nginx -t && systemctl reload nginx

Verify

# Check service
systemctl status putfs

# Test write
curl -X PUT -H "X-Api-Key: PUTFS_CHANGEME" -H "X-Api-Secret: CHANGEME" \
  -d "hello" http://localhost/test/hello.txt

# Test read
curl -H "X-Api-Key: PUTFS_CHANGEME" -H "X-Api-Secret: CHANGEME" \
  http://localhost/test/hello.txt

# Check the file on disk
ls -la /srv/putfs/test/hello.txt