From b9784bb2a77026c4572763073b3f872f4b158a18 Mon Sep 17 00:00:00 2001
From: Roi Talpaz <2651169+fokolo@users.noreply.github.com>
Date: Wed, 27 Nov 2024 17:57:06 +0200
Subject: [PATCH] Added more docs
---
docs/site/docs/customize-ui.md | 171 ++++++++++++++++++++
docs/site/docs/data-security.md | 9 +-
docs/site/docs/installation.md | 55 +++++++
docs/site/docs/intro.md | 33 ++++
docs/site/docusaurus.config.ts | 8 +-
docs/site/static/img/ocean-architecture.svg | 1 +
6 files changed, 274 insertions(+), 3 deletions(-)
create mode 100644 docs/site/static/img/ocean-architecture.svg
diff --git a/docs/site/docs/customize-ui.md b/docs/site/docs/customize-ui.md
index f96e787af..6f62afa70 100644
--- a/docs/site/docs/customize-ui.md
+++ b/docs/site/docs/customize-ui.md
@@ -3,3 +3,174 @@ sidebar_position: 3
---
# Customize UI
+
+The Port Backstage plugin is designed with flexibility in mind, allowing you to fully customize how data is presented in your Backstage instance. Since the Port SDK returns standard JavaScript objects, you have complete control over the presentation layer.
+
+## Understanding the Data Structure
+
+When you fetch data using the Port SDK, you receive plain JavaScript objects that you can manipulate and render however you prefer. For example:
+
+```typescript
+// Example of data returned from Port SDK
+const entityData = {
+ id: "entity-123",
+ title: "My Service",
+ properties: {
+ owner: "team-a",
+ status: "production",
+ scorecard: {
+ score: 85,
+ rules: [
+ /* ... */
+ ],
+ },
+ },
+};
+```
+
+## Creating Custom Components
+
+You can create your own components to display Port data in ways that match your organization's needs:
+
+```typescript
+import { usePortEntity } from "@port-labs/backstage-plugin-port-frontend";
+
+const CustomEntityCard = () => {
+ const { entity, loading } = usePortEntity("entity-id");
+
+ if (loading) return ;
+
+ return (
+
+ {/* Render entity data however you want */}
+ {entity.title}
+
+ {/* Add your custom styling and components */}
+
+ );
+};
+```
+
+## Customization Examples
+
+### 1. Custom Scorecard Visualization
+
+Instead of using the default scorecard view, you can create your own visualization:
+
+```typescript
+const CustomScorecard = () => {
+ const { scorecard } = usePortScorecard("scorecard-id");
+
+ return (
+
+ );
+};
+```
+
+### 2. Custom Entity List
+
+Create your own layout for displaying multiple entities:
+
+```typescript
+const CustomEntityList = () => {
+ const { entities } = usePortEntities();
+
+ return (
+
+ {entities.map((entity) => (
+
+ ))}
+
+ );
+};
+```
+
+## Integration with Existing Components
+
+You can easily integrate Port data with your existing Backstage components:
+
+```typescript
+import { Table } from "@backstage/core-components";
+
+const PortDataTable = () => {
+ const { entities } = usePortEntities();
+
+ const columns = [
+ { title: "Name", field: "title" },
+ { title: "Owner", field: "properties.owner" },
+ // Add more columns as needed
+ ];
+
+ return (
+
+ );
+};
+```
+
+## Best Practices
+
+1. **Data Transformation**
+
+ - Create utility functions to transform Port data into your preferred format
+ - Keep transformation logic separate from presentation components
+
+2. **Component Reusability**
+
+ - Build reusable components that can handle different types of Port entities
+ - Use TypeScript interfaces to ensure type safety
+
+3. **Performance**
+
+ - Implement proper loading states
+ - Consider pagination for large data sets
+ - Use memoization when appropriate
+
+4. **Error Handling**
+ - Add proper error boundaries
+ - Provide meaningful feedback to users when data loading fails
+
+## Available Hooks
+
+The Port frontend plugin provides several hooks to help you access and manipulate data:
+
+- `usePortEntity`: Fetch a single entity
+- `usePortEntities`: Fetch multiple entities
+- `usePortScorecard`: Fetch scorecard data
+- `usePortActions`: Access available actions
+- And more...
+
+## Example Repository
+
+For more examples and inspiration, check out our [example repository](https://github.com/port-labs/backstage-plugin-examples) containing various customization scenarios and implementations.
+
+## Need Help?
+
+If you need assistance with customizing your Port Backstage plugin UI:
+
+- Check our [API documentation](https://docs.getport.io/api-reference/port-api)
+- Join our [Community Discord](https://discord.com/invite/port-labs)
+- Open an issue in our [GitHub repository](https://github.com/port-labs/backstage-plugin)
+
+Remember, the flexibility of the Port SDK means you're not limited to any predefined layouts or styles. You can create exactly the user experience you want for your developers.
+
+If you need assistance with customizing your Port Backstage plugin UI:
+
+- Check our [API documentation](https://docs.getport.io/api-reference/port-api)
+- Join our [Community Discord](https://discord.com/invite/port-labs)
+- Open an issue in our [GitHub repository](https://github.com/port-labs/backstage-plugin)
+
+3. **Performance**
+ - Implement proper loading states
diff --git a/docs/site/docs/data-security.md b/docs/site/docs/data-security.md
index 8bb11c335..f2df10dd6 100644
--- a/docs/site/docs/data-security.md
+++ b/docs/site/docs/data-security.md
@@ -4,4 +4,11 @@ sidebar_position: 7
# Data handling & security
-Read more about how we handle data and security in the [Port official documentation](https://docs.getport.io/security).
+We do not store any secrets in Port SaaS. All secrets remain within your own infrastructure, and we never access them in the SaaS.
+
+The way we solve it is by using Ocean, our open-source data integration tool. which you can run on-prem. read more about it [here](https://ocean.getport.io/).
+
+The following diagram shows how the data flows between Ocean - on your own infrastructure - and Port, with only outgoing requests from your infrastructure to Port:
+
+
+Read more about how we handle data and security in our [official documentation](https://docs.getport.io/security).
diff --git a/docs/site/docs/installation.md b/docs/site/docs/installation.md
index a223ae040..04fa54d49 100644
--- a/docs/site/docs/installation.md
+++ b/docs/site/docs/installation.md
@@ -3,3 +3,58 @@ sidebar_position: 2
---
# Installation
+
+### Install Plugins
+
+Install frontend and backend plugins using yarn:
+
+```bash
+# Install backend plugin
+yarn add --cwd packages/backend @port-labs/backstage-plugin-port-backend
+
+# Install frontend plugin
+yarn add --cwd packages/app @port-labs/backstage-plugin-port-frontend
+```
+
+Then register the backend plugin in `packages/backend/src/index.ts`:
+
+```typescript
+backend.add(import("@port-labs/backstage-plugin-port-backend"));
+```
+
+Finally, add components as you like from the frontend plugin to your Backstage instance.
+
+For example, let's add the Scorecard component to the NavBar:
+
+in the file: `packages/app/src/App.tsx`, add the route:
+
+```typescript
+} />
+```
+
+and then add the link to the NavBar, in the file: `packages/app/src/components/Root/Root.tsx`:
+
+```typescript
+
+```
+
+
+
+### Configure Credentials
+
+1. In Port, on the top right, click on the `...` (three dots) and select **Credentials**.
+2. Generate API credentials (Client ID and Client Secret)
+3. Add these credentials to your Backstage's `app-config.yaml`:
+
+ ```yaml
+ port:
+ api:
+ baseUrl: https://api.getport.io
+ auth:
+ clientId: YOUR_CLIENT_ID
+ clientSecret: YOUR_CLIENT_SECRET
+ ```
+
+
+
+Read more [find your Port credentials](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)
diff --git a/docs/site/docs/intro.md b/docs/site/docs/intro.md
index 16f1a59b5..8b87ef135 100644
--- a/docs/site/docs/intro.md
+++ b/docs/site/docs/intro.md
@@ -4,3 +4,36 @@ slug: /
---
# Introduction
+
+The Port Backstage plugin allows you to ramp up your Backstage instance quickly.
+Building a developer portal from scratch can be a daunting task, but with the Port Backstage plugin, you can have a **fully functional portal in days not months**.
+
+
+
+
+
+With this plugin, you can:
+
+- Build new plugin with **PortSDK** in days and not months
+- Consolidate data from multiple sources into a single, unified view
+- Implement governance and compliance through Port's rules engine and scorecards
+- Enable self-service actions for developers
+- Integrate with 50+ tools and services through Port's extensive integration library
+
+## Key benefits
+
+1. **Simplified Integration**: Connect to dozens of data sources through a single plugin, eliminating the need to manage multiple individual Backstage plugins.
+
+2. **Flexible Data Modeling**: Shape and customize your data model in Port to display exactly the information your teams need in Backstage.
+
+3. **Governance & Compliance**: Use Port's rules engine and scorecards to define, measure, and enforce standards across your software catalog.
+
+4. **Enhanced Developer Experience**: Provide developers with a more comprehensive and actionable view of their services, including compliance scores, actions, and data from various integrations.
+
+5. **Rapid Setup**: Get up and running quickly with Port's easy-to-use interface for configuring integrations and data models.
+
+6. **Continuous Updates**: Benefit from Port's ongoing development of new integrations and features without waiting for individual Backstage plugin updates.
+
+This plugin is designed to complement and enhance your existing Backstage setup, allowing you to build a more powerful and tailored developer portal efficiently. Whether you're just getting started with Backstage or looking to take your existing instance to the next level, the Port plugin offers a flexible and scalable solution for your software catalog and developer portal needs.
+
+Let's get started with setting up the Port Backstage plugin and exploring its capabilities!
diff --git a/docs/site/docusaurus.config.ts b/docs/site/docusaurus.config.ts
index ea3a2bf01..567915f3c 100644
--- a/docs/site/docusaurus.config.ts
+++ b/docs/site/docusaurus.config.ts
@@ -83,8 +83,12 @@ const config: Config = {
title: "Docs",
items: [
{
- label: "Tutorial",
- to: "/docs",
+ label: "Getting Started",
+ to: "/docs/getting-started",
+ },
+ {
+ label: "Introduction",
+ to: "/docs/",
},
],
},
diff --git a/docs/site/static/img/ocean-architecture.svg b/docs/site/static/img/ocean-architecture.svg
new file mode 100644
index 000000000..7552921c0
--- /dev/null
+++ b/docs/site/static/img/ocean-architecture.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
+