Enterprise: Install

The Enterprise installer is an interactive shell script that sets up a complete single-node flexFS deployment — admin server, metadata server, optional caching proxy, and your first volume — in a single run. 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
• A flexFS license key (UUID format, obtained from Paradigm4)
• 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/enterprise/install.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.

License Key Validation

License key: ________

Enter your Enterprise license key. The installer validates that it is a properly formatted UUID, then contacts the flexFS licensing service to verify it. If validation fails you will see one of:

• invalid license key: not a UUID — the key is not in UUID format
• invalid license key: unauthorized — the key was rejected by the licensing service
• unable to validate license key — the licensing service could not be reached

Note

The license key is also used as the admin server’s authentication token. It is stored in the admin server credential file and must be kept secure.

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 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. If detection fails (for example, on a bare-metal server or a VM without metadata access), 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. This is useful when using an S3-compatible storage service with a non-AWS provider.

The installer then prompts for a custom object storage endpoint:

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

Leave this blank to use the provider’s default endpoint. Set it to reach an S3-compatible service (such as MinIO or Wasabi), a private or sovereign-cloud endpoint, or a local emulator.

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]: ________

The key prefix is a path within the bucket that flexFS uses to namespace its data. The default flexfs is suitable for most deployments.

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 yes. Otherwise, answer no and provide static credentials:

Username: ________
Password: ________

Host and Ports

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

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

Proxy Configuration

Enable caching proxy? [no]: ________

Proxy groups provide a CDN-like caching layer between mount clients and object storage. If you answer yes, the installer prompts for:

Proxy bind port [9443]: ________
Proxy cache folder [/cache]: ________
Proxy cache disk quota [95%]: ________
Max proxied blocks per file (0 = all) [0]: ________

The cache folder should be on a fast local disk (NVMe or SSD). The disk quota controls how much space the proxy’s on-disk cache can use, specified as a percentage or absolute size (e.g. 95%, 500GB, 1TiB). Max proxied blocks per file caps how many of each file’s leading blocks are served through the proxy — 0 proxies every block; a positive value proxies only that many leading blocks per file. It is a volume setting, applied to the volume created below, and only takes effect once a proxy exists.

Tip

You can skip the proxy during initial setup and add proxy groups later using configure.flexfs. See Proxy Server Setup for details.

Volume Configuration

(Block size, compression, and encryption cannot be changed after creation)

Volume name [vol-01]: ________
Block size (e.g. 1M, 2M, 4M) [4M]: ________
Compression algorithm (lz4, snappy, zstd, none) [lz4]: ________
Enable end-to-end encryption? [no]: ________

Setting	Choices	Notes
Volume name	Any string	Human-readable identifier for the volume
Block size	256KiB — 8MiB (power of 2)	Larger blocks suit large sequential files; smaller blocks suit many small files. Cannot be changed after creation.
Compression	lz4, snappy, zstd, none	LZ4 is the fastest; zstd provides the highest ratio. Cannot be changed after creation.
Encryption	yes / no	Enables AES-256 end-to-end encryption. Cannot be changed after creation.

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         instance role/principal

Host          10.0.1.50
Admin         :443
Meta          :8443

Volume        vol-01
Block size    4MiB
Compression   lz4
E2EE          disabled

Reporting     disabled

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

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

Proceed with installation? [yes]: ________

Answer yes to begin the installation.

The summary above shows a deployment without a caching proxy. When a proxy is enabled, the summary also lists a Proxy line (its bind port, cache folder, and disk quota), a Proxied line (how many leading blocks per file are served through the proxy), and the proxy’s port under Required TCP ports.

What Gets Installed

After confirmation, the installer executes the following steps automatically:

1. Downloads binaries to /sbin/:

   • admin.flexfs — admin server
   • meta.flexfs — metadata server
   • configure.flexfs — resource configuration CLI
   • manage.flexfs — host management CLI
   • proxy.flexfs — caching proxy (if enabled)

   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 and starts the admin server

   • Creates credential file at ~root/.flexfs/admin/
   • Creates a systemd unit (flexfs-admin.service)
   • Starts the service and waits up to 30 seconds for the health endpoint to respond

3. Saves the license grant for offline validation

4. Initializes configure.flexfs with the admin server address and account token

5. Creates the infrastructure using configure.flexfs:

   • A provider (e.g. aws, gcp)
   • A region (e.g. us-east-1)
   • A block store linking the provider, region, bucket, and credentials
   • A meta store pointing to the metadata server address (an authentication token is auto-generated)
   • A proxy group (if proxy was enabled), linking the provider, region, and proxy address

6. Initializes and starts the metadata server

   • Creates credentials with the admin server address and meta store token
   • Creates a systemd unit (flexfs-meta.service)
   • Starts the service

7. Initializes and starts the proxy server (if enabled)

   • Creates credentials with object storage credentials
   • Creates a systemd unit (flexfs-proxy.service) with the configured bind address, cache folder, and disk quota
   • Starts the service

8. Deploys mount client binaries to the admin server’s deploy folder using manage.flexfs deploy

9. Creates the volume with the specified block size, compression, and encryption settings

10. Creates a volume token for client authentication

11. Links the volume to the proxy group (if proxy was enabled)

12. Verifies that all services are running and responds on their health endpoints

After Installation

When the installer completes successfully, it displays:

================================================================================
flexFS Enterprise Edition Is Running!
================================================================================

Admin server:  https://10.0.1.50:443
Meta server:   https://10.0.1.50:8443

Management:

  configure.flexfs    configure volume, proxies, and tokens
  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/vol-01 <volume-token>

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

The mount command shown uses the volume token created during installation. You can copy this command and run it on any client host to mount the filesystem.

Systemd Services

The installer creates the following systemd units:

Service	Unit name
Admin server	flexfs-admin.service
Metadata server	flexfs-meta.service
Proxy server	flexfs-proxy.service (if enabled)

Check status with:

systemctl status flexfs-admin flexfs-meta flexfs-proxy

You can also use the manage.flexfs utility to monitor and control services:

manage.flexfs status

See manage.flexfs for the full set of commands (start, stop, restart, upgrade, watch, and more).

Next Steps

• Enterprise: Configuration — learn how to manage resources with configure.flexfs
• Enterprise: First Mount — install the mount client on a remote host