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. 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 and credentials (or an instance role)

Run the Installer

Download and run the installer as root:

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

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

Installation Walkthrough

Pre-flight Checks

The installer begins by verifying 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]: ________

Answering yes will stop all running flexFS services and remove the existing installation before proceeding.

Cloud Auto-Detection

The installer attempts to detect the cloud provider and region by querying instance metadata endpoints:

Provider	Detection method
AWS	IMDSv2 token + /latest/meta-data/placement/region
GCP	Metadata-Flavor: Google header + zone-to-region extraction
Azure	IMDS /metadata/instance/compute/location
OCI	IMDS /opc/v2/instance/regionInfo/regionIdentifier

If detection succeeds, the provider and region are pre-filled as defaults. If detection fails, you enter them manually.

Cloud Configuration

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

The storage API is derived automatically from the provider (aws maps to s3, gcp to gcs, etc.) but can be overridden.

If you select the s3 API, an additional prompt appears:

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

Leave this blank for standard AWS S3. Provide a custom endpoint URL for S3-compatible services.

Next, provide the bucket and key prefix:

Bucket name: ________
Key prefix [flexfs]: ________

Credentials

Have you attached an instance role/principal? [yes]: ________

If your host uses an IAM role, managed identity, or instance principal for bucket access, accept the default. Otherwise, answer no and provide static credentials:

Username: ________
Password: ________

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.

Summary and Confirmation

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

================================================================================
Installation Summary
================================================================================
Provider   aws
Region     us-east-1
API        s3
Bucket     my-flexfs-bucket
Prefix     flexfs
Creds      instance role/principal

Host       10.0.1.50
Server     :443
Meta       :8443

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.

What Gets Installed

After confirmation, the installer executes the following steps automatically:

1. Downloads binaries to /usr/sbin/:

   • free.flexfs — free admin server
   • meta.flexfs — metadata server

   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 (/v1/status) for up to 30 seconds

Note

Unlike the Enterprise installer, the Community installer does not download configure.flexfs, manage.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)

These settings are fixed and cannot be changed in the Community edition. 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

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

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

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