Getting Started with Xferity — Deploy and Run Your First Flow

Getting Started

This guide is the shortest path to a first working Xferity deployment.

The goal is to get from an empty runtime layout to one validated managed file transfer flow with enough operator visibility to confirm that it worked.

Before you start

Prepare:

• a host where you can run Xferity as a native binary or Docker container
• one reachable endpoint such as SFTP, FTPS, S3-compatible storage, or AS2
• the required trust material for that endpoint
• any OpenPGP keys or certificates required by the flow

For a first evaluation, use one partner and one simple flow.

Recommended first path

For most teams, the simplest first path is:

1. choose a file-backed deployment
2. create the runtime directory layout
3. write a minimal global configuration
4. define one partner
5. define one flow
6. run validate
7. run diag
8. run the flow once manually
9. review logs, status, and audit output

This sequence keeps problems isolated. It is easier to debug one manual run than a scheduled flow plus workers plus UI authentication all at once.

Step 1: choose a deployment shape

For an initial test, start with one of these:

• a local Docker deployment
• a single native binary
• a Windows-native deployment if that matches your environment

If you do not already need workers, sessions, or Postgres-backed state, start with file-backed mode.

See Deployment.

Step 2: create the runtime layout

Create directories for:

• config
• flows
• partners
• logs
• audit files
• state
• storage landing or staging paths
• keys and certificates

These choices affect permissions and backups later, so pick them deliberately.

Step 3: write a minimal global configuration

The first configuration should do only what is required to run one flow:

• set flows_path and partners_dir
• choose the state backend
• set storage.base_path
• configure logging
• enable audit logging if you want first-run traceability

Do not add OIDC, multiple secret backends, or Postgres workers unless you need them for the first run.

Step 4: define one partner

Create one partner definition with:

• the protocol
• endpoint location
• authentication settings
• trust material such as SSH host data, FTPS CA material, or AS2 certificate bindings

Use secret references instead of plaintext values where practical.

Step 5: define one flow

Your first flow should be simple:

• one source
• one destination
• minimal file matching
• clear local landing or staging paths
• no aggressive cleanup until the path is proven

The goal is to verify the end-to-end runtime path, not to model the full production workflow yet.

Step 6: validate before execution

Run:

• validate
• diag

Validation uses strict YAML parsing, so misspelled or unsupported fields are rejected rather than ignored.

Diagnostics help surface endpoint, key, certificate, and filesystem issues before you run the flow.

Step 7: run the flow once

Run the flow manually first:

xferity run <flow-name>

If you need a non-destructive check and the flow path supports it, you can also use:

xferity run <flow-name> --dry-run

Step 8: review operator signals

After the first run, inspect:

• flow status
• flow history <flow>
• logs <flow>
• trace <file> when you want file lifecycle detail

If the Web UI is enabled, you can also review pages and API results there.

Common first-run mistakes

Common setup mistakes include:

• treating trust material as optional
• placing plaintext secrets directly in config
• using schedules before a manual run succeeds
• enabling too many features before one path works
• not checking logs and audit output after the first run

What to do next

• Automation for schedules, retries, and operational behavior
• Configuration for the configuration model
• Protocols for protocol-specific detail
• Deployment for deployment patterns