> For the complete documentation index, see [llms.txt](https://docs.rely.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rely.io/plugins-and-automation/plugin-installation-guides/backstage.md).

# Backstage

{% hint style="info" %}
This plugin is part of Pro and Enterprise plan only
{% endhint %}

## Rely Migration Plugin for Backstage

Welcome to the `rely-migration-plugin` for Backstage by Rely.io. This plugin seamlessly integrates with Backstage to export essential data to the Rely.io Identity Data Provider (IDP). It offers two modes of operation: a one-time data export via a dedicated endpoint, and an automated, scheduled data export using a cron job.

Feel free to reference the NPM package page for more detailed information.

### Features

* **One-time Export**: Easily migrate your data to Rely.io with a single API call.
* **Scheduled Export**: Set up a cron job to regularly export data, ensuring continuous synchronization with Rely.io.

### Installation

To get started with the Rely Migration Plugin, follow these installation steps:

1. **Install the Plugin**:

   ```
   cd packages/backend && yarn add @rely/backstage-plugin-rely-migration-plugin-backend
   ```
2. **Create the Plugin File**: In your Backstage backend, create a new file at `packages/backend/src/plugins/rely.ts` with the following content:

   ```
   import { PluginEnvironment } from '../types';
   import { createRouter } from '@rely/backstage-plugin-rely-migration-plugin-backend';
   import { parseConfigs } from '@rely/backstage-plugin-rely-migration-plugin-backend';

   export default async function createPlugin(env: PluginEnvironment) {
     const routerOptions = await parseConfigs(env);
     return await createRouter(routerOptions);
   }
   ```
3. **Update the Backend Index**: Modify `packages/backend/src/index.ts` to include the Rely plugin:

   ```
   import rely from './plugins/rely';
   ...
   const relyEnv = useHotMemoize(module, () => createEnv('rely'));
   ...
   apiRouter.use('/rely', await rely(relyEnv));
   ```
4. **Configure Proxy and Rely in `app-config.yaml`**: Add the following configuration to your `app-config.yaml`:

   ```
   proxy:
     '/rely':
       target: https://magneto.rely.io
       headers:
         Authorization: Bearer <WEBHOOK_API_TOKEN_ON https://webapp.rely.io/settings>

   rely:
     # Enable/disable gzip
     cron:
       enabled: true
       schedule: '0 * * * *'
     # Define entity filters for data export
     entityFilters: []
       # Example filters:
       # - kind: ['API', 'Component']
       # - metadata.name: 'a'
       #   metadata.namespace: 'b'
   ```

### How to Use

* **One-time Export**: Trigger the endpoint `<backstage-hostname>/api/rely/migrate` to start a one-time export.
* **Scheduled Export**: If the cron job is enabled in the configuration, the plugin will automatically export data at specified intervals.

### Configuration Details

* `cron.enabled`: Enable or disable the cron job for scheduled exports.
* `cron.schedule`: Define the cron schedule for automated data exports.
* `entityFilters`: Specify filters for the entities to be exported. For more details on structuring these filters, refer to the [Backstage EntityFilterQuery documentation](https://backstage.io/docs/reference/catalog-client.entityfilterquery/).

### Development and Local Testing

* **Running in the Backstage App**: Start the Backstage app (`yarn start` at the root) and navigate to `/rely-migration-plugin`.
* **Isolated Plugin Development**: Run `yarn start` in the plugin directory for faster iteration, startup, and hot reloads. This setup is intended for local development only.

***

Thank you for choosing Rely.io for your identity management solutions. We are committed to providing seamless integration and top-notch support for Backstage users. For any issues or contributions, please feel free to open an issue or pull request in our repository.