File Storage (On-Premise)

On-Premise only

File Storage configuration applies exclusively to self-hosted (on-premise) installations of Floogos. In the cloud (SaaS) version, file storage is managed internally and requires no configuration.

---

What is file storage?

Several nodes generate files during workflow execution — Excel reports, PDFs, JSON exports, ZIP archives — and expose them through a download URL that downstream nodes or end users can access.

By default those files are written to a local folder (./temporal) on the engine server. This works fine for single-instance deployments, but fails in high-availability setups where multiple engine instances share traffic: a file written on instance A does not exist on instance B.

Floogos supports three storage backends to address this:

Backend	When to use
local	Single instance. Zero config. Default.
nfs	Multiple instances on the same network. Requires an NFS mount on every server.
bucket	Multi-instance or multi-region. No shared network needed. Works with Linode Object Storage, AWS S3, MinIO, Cloudflare R2, and any S3-compatible provider.

---

Nodes that use file storage

Node	Output
Save to Excel	.xlsx spreadsheet
Base64 to File	Any file decoded from a base64 string
Schema to Excel	.xlsx from database schemas
Save to JSON	.json data export
Format Excel from Summary	.csv batch summary
Hub Fiscal Export PDF	.pdf / .html / .zip of fiscal tickets

All these nodes automatically use whichever backend is active. No changes are needed in the workflow configuration itself.

---

File structure

The same folder layout is used in all three backends:

cli_101/
  report-1750000000000.xlsx
  invoice-1750000001234.pdf
cli_202/
  export-1750000005678.zip

In bucket mode cli_101/ is an object key prefix, not a real folder.

---

Backend: local (default)

No additional configuration required.

# Nothing to add — this is the default behavior
# Files are stored at ./temporal/cli_{id}/

---

Backend: nfs

Step 1 — Mount the NFS on every engine instance:

sudo apt-get install -y nfs-common
sudo mkdir -p /var/www/nfs
sudo chown -R nodeuser:nodeuser /var/www/nfs

# Mount (replace with your NFS server IP and export path)
sudo mount -t nfs 10.0.0.5:/exports/floogos /var/www/nfs

# Make it permanent — add to /etc/fstab
10.0.0.5:/exports/floogos  /var/www/nfs  nfs  defaults,_netdev  0  0

On-premise installations only

Environment variables are set on the server where Floogos runs, so they apply to on-premise installations. On Floogos Cloud you don’t have access to them — these values are managed by the Floogos team. If you need one changed for your account, get in touch with support.

Step 2 — Set environment variables:

STORAGE_TYPE=nfs
STORAGE_PATH=/var/www/nfs

# Optional — if nginx serves the files directly from the NFS mount
# Without this, download URLs use ENGINE_HOST/download/...
STORAGE_URL=https://static.yourcompany.com

Optional nginx config to serve NFS files directly:

location /files/ {
    alias /var/www/nfs/;
    add_header Content-Disposition "attachment";
    location ~ ^/files/cli_[0-9]+/ { allow all; }
    deny all;
}

With that nginx block: STORAGE_URL=https://yourcompany.com/files

---

Backend: bucket (S3-compatible)

Supported providers: Linode Object Storage, AWS S3, MinIO, Cloudflare R2, and any S3-compatible API.

STORAGE_TYPE=bucket

# S3-compatible endpoint (omit for standard AWS S3)
STORAGE_BUCKET_ENDPOINT=https://us-east-1.linodeobjects.com

STORAGE_BUCKET_REGION=us-east-1
STORAGE_BUCKET_NAME=floogos-files
STORAGE_BUCKET_KEY=your_access_key_id
STORAGE_BUCKET_SECRET=your_secret_access_key

# Optional — public base URL (CDN, custom domain, etc.)
# If omitted, the engine builds the URL from ENDPOINT + BUCKET_NAME
STORAGE_URL=https://floogos-files.us-east-1.linodeobjects.com

The bucket must be publicly readable so users can download files directly. If you need private access, generate pre-signed URLs using the AWS S3 node after writing the file.

Linode Object Storage — full example

STORAGE_TYPE=bucket
STORAGE_BUCKET_ENDPOINT=https://us-east-1.linodeobjects.com
STORAGE_BUCKET_REGION=us-east-1
STORAGE_BUCKET_NAME=my-company-floogos
STORAGE_BUCKET_KEY=LINODE_ACCESS_KEY
STORAGE_BUCKET_SECRET=LINODE_SECRET_KEY
STORAGE_URL=https://my-company-floogos.us-east-1.linodeobjects.com

AWS S3 — full example

STORAGE_TYPE=bucket
STORAGE_BUCKET_REGION=eu-west-1
STORAGE_BUCKET_NAME=my-company-floogos
STORAGE_BUCKET_KEY=AKIAIOSFODNN7EXAMPLE
STORAGE_BUCKET_SECRET=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# STORAGE_BUCKET_ENDPOINT is not needed for standard AWS S3
STORAGE_URL=https://my-company-floogos.s3.eu-west-1.amazonaws.com

MinIO — full example

STORAGE_TYPE=bucket
STORAGE_BUCKET_ENDPOINT=https://minio.yourcompany.com
STORAGE_BUCKET_REGION=us-east-1
STORAGE_BUCKET_NAME=floogos
STORAGE_BUCKET_KEY=minioadmin
STORAGE_BUCKET_SECRET=minioadmin
STORAGE_URL=https://minio.yourcompany.com/floogos

---

Environment variable reference

Variable	Backend	Required	Example
STORAGE_TYPE	all	No (default: local)	nfs | bucket
STORAGE_PATH	nfs	Yes	/var/www/nfs
STORAGE_URL	nfs, bucket	No	https://static.yourcompany.com
STORAGE_BUCKET_ENDPOINT	bucket	No*	https://us-east-1.linodeobjects.com
STORAGE_BUCKET_REGION	bucket	Yes	us-east-1
STORAGE_BUCKET_NAME	bucket	Yes	floogos-files
STORAGE_BUCKET_KEY	bucket	Yes	access key ID
STORAGE_BUCKET_SECRET	bucket	Yes	secret access key

*STORAGE_BUCKET_ENDPOINT is required for Linode, MinIO, Cloudflare R2. Omit for standard AWS S3.

---

Applying the configuration

Restart the engine after setting environment variables:

pm2 restart all
# or
systemctl restart floogos-engine

On startup the engine logs the active backend:

# Local
📁 [Storage] backend=local basePath=/srv/floogos/temporal

# NFS
📁 [Storage] backend=nfs basePath=/var/www/nfs

# Bucket
📁 [Storage] backend=bucket bucket=floogos-files

If backend=local appears when you expected another backend, the environment variables were not loaded correctly.

---

Automatic file cleanup

The engine deletes old files automatically every day at 02:00 UTC.

Backend	Default TTL
local	72 hours (3 days)
nfs	168 hours (7 days)
bucket	168 hours (7 days) — uses ListObjectsV2 + DeleteObject, no egress cost

For files that need permanent storage, use the AWS S3 node or Google Drive node after the file-generating node.

---

Troubleshooting

Download URLs return 404

• NFS: verify the mount is active (df -h | grep nfs) and nginx points to the same path
• Bucket: verify the bucket is public and STORAGE_URL matches the provider endpoint

Files are not being created

• NFS: test write permissions: sudo -u nodeuser touch /var/www/nfs/test.txt
• Bucket: verify keys have s3:PutObject permission; test with AWS CLI:

  aws s3 cp test.txt s3://floogos-files/ --endpoint-url https://us-east-1.linodeobjects.com

In HA setups, one instance can’t see files from another

• NFS: confirm the NFS is mounted on every instance
• Bucket: this should not happen with bucket — all instances read from the same S3 endpoint

Cleanup is not deleting bucket objects

• Verify keys have s3:ListBucket and s3:DeleteObject permissions
• Check engine logs at 02:00 UTC: pm2 logs | grep "Storage cleanup"