Community: Install

The Community installer is an interactive shell script that sets up a complete single-node flexFS deployment — free admin server, metadata server, and a single pre-configured volume — in a single run. No license key is required, but you must accept the Usage Agreement before installation proceeds. After installation you will have a working system ready for mount clients to connect.

Before You Begin

Ensure you have:

• A Linux host meeting the prerequisites
• Root access
• An object storage bucket, with credentials for it or a cloud identity attached to the host that grants access to it

Run the Installer

Download and run the installer as root:

curl -fsSL https://get.flexfs.io/community/install.sh | sudo bash

The script runs interactively, prompting for configuration at each step. The sections below describe each prompt in order.

Each answer is saved as it is given to /root/.flexfs-community-install.answers, a file only root can read. If the installer is interrupted, running it again offers the saved answers as defaults. The secret access key, the storage account access key, the license acceptance, and confirmations are not saved and must be entered again. The file is deleted when the installation completes; delete it to start over.

Installation Walkthrough

License Agreement

The installer first presents the flexFS Community Edition Usage Agreement and asks you to confirm acceptance:

IMPORTANT: The flexFS Community Edition is subject to the flexFS Community
Edition Usage Agreement. Please review the full terms and conditions at:

  https://www.flexfs.io/flexfs-community-usage-agreement.pdf

By typing 'yes' below, you confirm that you have read, understand, and agree
to the terms of the flexFS Community Edition Usage Agreement.

Do you accept the license agreement? [no]: ________

You must answer yes to continue. The installer exits if you decline.

Pre-flight Checks

The installer then verifies that:

1. You are running as root (uid 0)
2. curl and systemctl are available on the host

If any check fails the script exits immediately with an error message.

Existing Installation Detection

If the installer finds an existing flexFS installation at ~root/.flexfs, it prompts:

An existing flexFS installation was found at /root/.flexfs.
Overwrite existing installation? [no]: ________

On a host with an Enterprise installation, the first line names it as one. Answering yes shows a warning and asks you to type overwrite to confirm. Once you confirm the installation summary, the installer unmounts every flexFS mount on the host (aborting if one is still in use), stops and removes every flexFS server on the host, including the admin and proxy servers of an Enterprise installation, and permanently deletes ~root/.flexfs, including the metadata database of every volume served from this host; without it, the data those volumes keep in object storage cannot be read. To move an existing installation to a new version, use manage.flexfs upgrade instead of re-running the installer. To convert it to Enterprise, run the Enterprise installer and choose upgrade.

Cloud Auto-Detection

The installer automatically detects the cloud provider (AWS, GCP, Azure, or OCI) and region from the host’s instance metadata. If detection succeeds, the provider and region are pre-filled as defaults. On a host outside a cloud, such as an on-premises server, the installer reports that no cloud environment was detected and you enter them yourself.

Cloud Configuration

Object storage provider (e.g. aws, gcp, azure, oci, dc-1) [detected]: ________
Region (e.g. us-east-1) [detected]: ________
Object storage API (s3, gcs, azure, oci) [derived]: ________

The provider is the one whose object storage holds the bucket, which need not be where the host runs: an on-premises host can store its data in AWS, GCP, Azure or OCI object storage. For other S3-compatible storage, such as MinIO or Ceph, enter a name of your choice (for example onprem); the region prompt then explains that the region is used to sign requests and defaults to us-east-1, which such storage usually accepts.

The storage API is derived from the provider (aws maps to s3, gcp to gcs, azure to azure, oci to oci, and any other name to s3) but can be overridden, for example to use a cloud’s S3-compatible interface.

The installer then prompts for the object storage endpoint. With a cloud provider’s own API (aws with s3, gcp with gcs, azure with azure, or oci with oci) the endpoint is optional:

Custom endpoint (leave blank for the provider default) []: ________

Leave it blank to use the provider’s default endpoint, or set it for a private or sovereign-cloud endpoint. For any other combination the endpoint is required, since there is no default to fall back on:

Object storage endpoint (e.g. https://storage.example.com:9000): ________

With gcp and the s3 API it defaults to https://storage.googleapis.com. The endpoint, bucket name, OCI namespace, OCIDs, and key fingerprint are checked as they are entered and asked for again if invalid; IPv6 addresses in an endpoint go in brackets. When a saved answer from an interrupted run is offered as the default for an optional prompt, enter - to clear it.

Next, provide the bucket name:

Bucket name: ________

Choosing the oci API then prompts for the tenancy’s object storage namespace. When the OCI CLI is installed the installer looks it up and offers it as the default:

Object storage namespace [<namespace>]: ________

Finally, provide the key prefix:

Key prefix [flexfs]: ________

Object Storage Credentials

When the host is detected on the cloud chosen as the provider and the storage API is that cloud’s native one (aws with s3, gcp with gcs, azure with azure, or oci with oci), the installer offers the host’s own cloud identity:

Use this instance's IAM instance role for object storage access? [yes]: ________

The question names the IAM instance role (AWS), attached service account (GCP), managed identity (Azure), or instance principal (OCI). Accept the default if that identity grants access to the bucket (see Cloud IAM Setup). On an EC2 instance with no IAM role attached, the installer says so and the question defaults to no. With the managed identity and no custom endpoint, the installer then asks for the storage account name, which it needs to form the default service URL:

Storage account name: ________

If you answer no, or the question is not asked (off-cloud, or a provider or API that does not match the detected cloud), the installer asks for credentials for the chosen API:

API	Prompts
s3	Access key ID, Secret access key
gcs	Path to the service account key file (JSON)
azure	Storage account name, Storage account access key
oci	User OCID, Tenancy OCID, API key fingerprint, Path to the API private key file (PEM)

The secret access key and the storage account access key are not shown as you type and are asked for twice. Key files are read from the path given and checked; the installer asks again if a file cannot be read, does not contain a private key, or holds an encrypted key.

With the s3, gcs, or oci API, when root already has credentials configured for that API and the servers would use them, the installer first offers a choice between entering credentials and using the configured ones:

Credential type:
  1) access key ID and secret access key
  2) AWS credentials already configured in /root/.aws
Choose 1 or 2 [1]: ________

API	Configured credentials
s3	The [default] profile in /root/.aws/credentials, or credentials or a role in the [default] profile of /root/.aws/config
gcs	/root/.config/gcloud/application_default_credentials.json
oci	The [DEFAULT] profile in /root/.oci/config

Choose 2 to have the servers use the configured credentials; no further credentials are asked for. The choice is not offered on an EC2 instance with an IAM role attached or on an OCI instance, because the servers use the instance’s identity ahead of configured credentials there. On GCP, application default credentials configured for root take precedence over the attached service account, and the installer says so when you choose the service account.

Host and Ports

Host IP address [auto-detected]: ________
Free admin server port [443]: ________
Metadata server port [8443]: ________

The host IP address is auto-detected from the local network interface. The free server and metadata ports must be different. These are the addresses that mount clients will use to connect.

Error Reporting

Report errors to Paradigm4? [no]: ________

FlexFS can report errors and panics to Paradigm4 to help diagnose problems. Reports carry the error text, a stack trace, and the failing service’s log. Reporting is off by default; answer yes to enable it for the servers and mount clients.

Summary and Confirmation

Before making any changes, the installer displays a full summary:

================================================================================
Installation Summary
================================================================================
Provider   aws
Region     us-east-1
API        s3
Bucket     <bucket>
Prefix     flexfs
Creds      IAM instance role

Host       10.0.1.50
Server     :443
Meta       :8443

Reporting  disabled

Required TCP ports (ensure these are reachable by mount clients):

    443  - free.flexfs (admin API and mount client installer)
   8443  - meta.flexfs (metadata service)

Proceed with installation? [yes]: ________

Answer yes to begin the installation.

The Creds line describes the chosen credentials, such as IAM instance role or access key (ID: <access-key-id>).

What Gets Installed

After confirmation, the installer executes the following steps automatically:

1. Downloads binaries to /sbin/:

   • free.flexfs — free admin server
   • meta.flexfs — metadata server
   • manage.flexfs — host management CLI

   Binaries are downloaded from https://get.flexfs.io/ for the detected platform (linux/amd64 or linux/arm64). SELinux contexts are restored if restorecon is available.

2. Initializes credentials for both services:

   • The free server credential file is written to ~root/.flexfs/free/creds with the cloud provider, region, API, bucket, prefix, metadata server address, and auto-generated tokens (account token, meta token, volume token, and a deterministic volume ID)
   • The metadata server credential file is written to ~root/.flexfs/meta/creds

3. Creates systemd units for both services:

   • flexfs-free.service
   • flexfs-meta.service

4. Starts services in order — the free server first, then the metadata server

5. Waits for readiness — polls the free server health endpoint (/status) for up to 30 seconds

Note

Unlike the Enterprise installer, the Community installer does not download configure.flexfs or proxy.flexfs. The single volume is pre-configured with sensible defaults and managed by the free server directly.

Pre-configured Volume

The Community edition creates a single volume named free with the following settings:

Setting	Value
Block size	2 MiB
Compression	lz4
End-to-end encryption	Disabled
Max blocks	2,621,440 (5 TiB at 2 MiB block size)
Max inodes	5,000,000
Retention	604,800 seconds (7 days)

Block size, compression, encryption and the two quotas are compiled into the Community server and cannot be changed. Two values are configurable: the retention period and the flags carried by the volume token (admin by default, which allows reporting queries). Both are read from the free server’s credentials file (/root/.flexfs/free/creds on an installer-built host), as retention (seconds, or a duration such as "7d" or "36h"; -1 or "forever" = forever) and volumeFlags, every time the server starts. The installer does not prompt for them. To change either, edit the file and restart the free server with sudo manage.flexfs restart free. The free server does not start if either value is invalid, so check volumeFlags against the flags listed under volume tokens before restarting.

Caution

Do not re-run free.flexfs init creds on a running installation to change these values. Each run mints new account, metadata and volume tokens, so the metadata server can no longer authenticate and every mount client’s stored token stops working. Edit the credentials file instead.

If you need multiple volumes, configurable block sizes, end-to-end encryption, or proxy groups, consider upgrading to Enterprise.

After Installation

When the installer completes successfully, it displays:

================================================================================
flexFS Community Edition Is Running!
================================================================================

Free server: https://10.0.1.50:443
Meta Server: https://10.0.1.50:8443

Management:

  manage.flexfs       manage, monitor, and update this server

To mount flexFS on a client machine, run:

  curl -fksSL https://10.0.1.50:443/deploy/install-mount.sh | sudo bash -s /mnt/flexfs/free

================================================================================

Copy the curl command and run it on any client host to mount the filesystem. Note that in the Community edition, the volume token is embedded in the deploy script — you only need to specify the mount point.

Systemd Services

Service	Unit name
Free admin server	flexfs-free.service
Metadata server	flexfs-meta.service

Check status with:

systemctl status flexfs-free flexfs-meta

Next Steps

• Community: Configuration — view the pre-configured volume and token
• Community: First Mount — install the mount client on a remote host