Merge pull request #2 from axelerant/platformsh-plugin-readme

Platformsh plugin readme

plugins/platformsh-backend/README.md

@@ -1,14 +1,33 @@
-# platformsh
+# Platform.sh Backend Plugin
 
-Welcome to the platformsh backend plugin!
+Backend plugin for the [Platform.sh frontend plugin](https://github.com/axelerant/backstage-plugins/tree/main/plugins/platformsh).
 
-_This plugin was created through the Backstage CLI_
+## Setup
 
-## Getting started
+1. Install the plugin:
 
-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn
-start` in the root directory, and then navigating to [/platformsh/health](http://localhost:7007/api/platformsh/health).
+   ```bash
+   yarn --cwd packages/backend add @axelerant/backstage-plugin-platformsh-backend
+   ```
 
-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
+2. Add the plugin to the backend package:
+
+   In your `packages/backend/src/index.ts`, make the following changes:
+
+   ```diff
+   import { createBackend } from '@backstage/backend-defaults';
+
+   const backend = createBackend();
+
+   + backend.add(import('@axelerant/backstage-plugin-platformsh-backend'));
+
+   backend.start();
+   ```
+
+3. Configure a CLI token. You can create a token at [https://console.platform.sh/-/users/<your-user-name>/settings/tokens](https://console.platform.sh/-/users/<your-user-name>/settings/tokens).
+
+   ```yaml
+   # app-config.yaml
+   platformsh:
+     cli_token: <cli-token>
+   ```

plugins/platformsh-common/README.md

@@ -1,5 +1,3 @@
-# @internal/backstage-plugin-platformsh-common
+# Platformsh Common
 
-Welcome to the common package for the platformsh plugin!
-
-_This plugin was created through the Backstage CLI_
+Common types and functionalities for the [Platformsh](https://github.com/axelerant/backstage-plugins/tree/main/plugins/platformsh) plugin.

plugins/platformsh/README.md

@@ -1,13 +1,96 @@
-# platformsh
+# Backstage Platform.sh Plugin
 
-Welcome to the platformsh plugin!
+A Backstage plugin that retrieves project details and environment data from Platform.sh.
 
-_This plugin was created through the Backstage CLI_
+## Features
 
-## Getting started
+- A page to list all projects from Platform.sh.
+- An entity card to display the current project details.
+- An entity card to display all environments for the current project.
+- Options to resume, pause, activate, deactivate, or delete development environments.
+- Permission support for environment actions.
 
-Your plugin has been added to the example app in this repository, meaning you'll be able to access it by running `yarn start` in the root directory, and then navigating to [/platformsh](http://localhost:3000/platformsh).
+## Setup
 
-You can also serve the plugin in isolation by running `yarn start` in the plugin directory.
-This method of serving the plugin provides quicker iteration speed and a faster startup and hot reloads.
-It is only meant for local development, and the setup for it can be found inside the [/dev](./dev) directory.
+The following sections will guide you through setting up and running the Platform.sh plugin.
+
+### Platform.sh Backend
+
+Before proceeding, ensure that you have set up the [Platform.sh Backend plugin](https://github.com/axelerant/backstage-plugins/tree/main/plugins/platformsh-backend).
+
+### Entity Annotation
+
+To use the Platform.sh plugin, add the following annotation to the entities you want to associate with Platform.sh:
+
+```yaml
+platform.sh/project-id: <platformsh-project-id>
+```
+
+### Installation
+
+To get the Platform.sh component working, follow these steps:
+
+1. First, add the `@axelerant/backstage-plugin-platformsh` package to your frontend app:
+
+   ```bash
+   # From your Backstage root directory
+   yarn --cwd packages/app add @axelerant/backstage-plugin-platformsh
+   ```
+
+2. The Platform.sh plugin provides a page component to list all projects from Platform.sh.
+
+   - Add a route to `App.tsx`:
+
+     ```ts
+     // Import the page component
+     import { PlatformshPage } from '@axelerant/backstage-plugin-platformsh';
+
+     // Add the route
+     <Route path="/platformsh" element={<PlatformshPage />} />;
+     ```
+
+   - Add a menu item to the sidebar in `Root.tsx`:
+
+     ```ts
+     // Import an icon
+     import StorageIcon from '@material-ui/icons/Storage';
+
+     // Add to the sidebar items list
+     <SidebarItem icon={StorageIcon} to="platformsh" text="Platform.sh" />;
+     ```
+
+3. The Platform.sh plugin provides an entity tab component named `EntityPlatformshContents`.
+
+   ```ts
+   // At the top imports
+   import { EntityPlatformshContents } from '@axelerant/backstage-plugin-platformsh';
+
+   // Add the tab to any entity page, using the service entity page as an example.
+   const serviceEntityPage = (
+     <EntityLayout>
+       {/* other tabs... */}
+       <EntityLayout.Route path="/platformsh" title="Platform.sh">
+         <EntityPlatformshContents />
+       </EntityLayout.Route>
+     </EntityLayout>
+   );
+   ```
+
+**Note:** This requires entities to have the Platform.sh annotation `platform.sh/project-id: <project-id>`. If not set, a missing annotation warning will be displayed.
+
+To display the tab only for entities where `platform.sh/project-id: <project-id>` is available, the plugin provides a conditional export `isPlatformshAvailable`.
+
+    ```ts
+    // At the top imports
+    import { EntityPlatformshContents, isPlatformshAvailable } from '@axelerant/backstage-plugin-platformsh';
+
+    // Add the tab conditionally based on annotation availability
+    const serviceEntityPage = (
+      <EntityLayout>
+        {/* other tabs... */}
+        <EntityLayout.Route path="/platformsh" title="Platform.sh" if={isPlatformshAvailable}>
+          <EntityPlatformshContents />
+        </EntityLayout.Route>
+      </EntityLayout>
+    );
+    ```