Deploying

npx flatfile deploy

The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

For a production deployment, listeners can be hosted either in your cloud or directly on the Flatfile platform.

Flatfile-Hosted Agents (Recommended)

While your own cloud provides the maximum level of control over listener code, qualities such as availability and network performance are the responsibility of the hosting provider. Flatfile offers tooling to deploy and manage Listeners securely hosted and run in the Flatfile cloud giving you a more consistent, low-latency, high-availability experience.

Deploying An Agent

Once you have configured your a local configuration running, bundling and deploying your listener to the flatfile cloud can be done in a single command.

npx flatfile deploy

The CLI will attempt to locate the entrypoint of your listener in the following order:

• ./index.js,
• ./index.ts
• ./src/index.js
• ./src/index.ts

If your listener is in another location you can provide the path as an argument:

npx flatfile deploy ./path-to/listener.ts

The CLI will provide updates as it’s deploying:

> npx flatfile deploy
✔  Code package compiled to .flatfile/build.js
✔  Code package passed validation
✔  Environment "production" selected
✔  Event listener deployed and running on your environment "production". us_ag_1234

Set your target environment FLATFILE_ENVIRONMENT_ID and API token FLATFILE_API_KEY in your .env file to avoid entering them when prompted.

Dashboard Management

You can view and manage agents via the Flatfile Dashboard. The dashboard provides a simple interface for monitoring and controlling your deployed agents with the following capabilities:

Feature	Description
View Agent	Access details about your deployed agents including their latest deployment and last received event
View Logs	Monitor agent activity and troubleshoot issues by examining execution logs
Download Agent Code	Retrieve the deployed code for reference, backup, or refactoring purposes
Delete Agent	Remove agents that are no longer needed from your environment
Revert Agent	Roll back to a previous version if issues arise with newer deployments
Deploy Library Agents	Deploy pre-built agents from the Flatfile Agent Library

Re-Deploying

To update the code in your listener simply make the update your desire re-deploy. Agents are versioned and you may revert to a previous version at any time via the dashboard.

Multiple Agents

To deploy a second Agent without overwriting the first, specify a unique slug:

npx flatfile deploy -s pink

When you pass a slug, the CLI will create a new Agent with the specified slug. This allows you to deploy multiple Agents to the same environment.

To update an existing Agent, you can specify the slug of the Agent you want to update by running the same command, including the slug.

If you do not specify a slug and have only one or no deployed Agents the CLI will update your existing Agent, or create your first Agent. The slug for this agent will be default.

Hosting on Regional Servers

To deploy on a regional server, please contact our support team.

Regional servers are available upon request for those needing to host their applications closer to their user base, ensuring faster access and compliance with local data regulations.

URL References

Region	URL / SPACE_URL	API URL
UK	platform.uk.flatfile.com	platform.uk.flatfile.com/api
EU	platform.eu.flatfile.com	platform.eu.flatfile.com/api
AU	platform.au.flatfile.com	platform.au.flatfile.com/api
CA	platform.ca.flatfile.com	platform.ca.flatfile.com/api

Configuring API URL

When deploying, you can specify the FLATFILE_API_URL either in your project’s .env file or as an environment variable.

.env

FLATFILE_API_URL=platform.eu.flatfile.com

Embedding Via Space URL

To embed Flatfile in your application, include both apiUrl and spaceUrl in your FlatfileImporter configuration to specify your regional server:

const spaceProps: ISpace = {
  name: "Embedded Space",
  publishableKey: "pk_**********",
  apiUrl: "Regional API URL here",
  spaceUrl: "Regional Space URL here",
  workbook,
  listener,
  // Additional properties here
};

Configure API Client Environment

For direct API interactions, the FlatfileClient needs the environment parameter set to your selected regional API URL:

import { FlatfileClient } from "@flatfile/api";

const api = new FlatfileClient({
  environment: "Regional API URL here",
});

Self-Hosting

Hosting listener code in your own cloud works similarly to how we run the develop command in that:

1. The listener process is launched
2. It polls the Flatfile API for updates
3. It then responds to those Events accordingly

Reach out to support for learning how about hosting in your own cloud.

Related Commands

• develop - Run a local listener for development
• list - List all deployed agents in your environment
• download-agent - Download an agent from your environment
• delete - Delete an agent from your environment