documentation added

Signed-off-by: Mert Can Bilgiç <mert.bilgic@trendyol.com>
2021-02-25 17:24:49 +03:00
parent 32fac33d8d
commit cebda81000
7 changed files with 171 additions and 191 deletions
@@ -309,3 +309,94 @@ and read the static generated documentation files. When you start the backend of
 the app, you should be able to see
 `techdocs info Successfully connected to the Azure Blob Storage container` in
 the logs.
+
+## Configuring OpenStack Swift Container with TechDocs
+
+Follow the
+[official OpenStack Api documentation](https://docs.openstack.org/api-ref/identity/v3/)
+for the latest instructions on the following steps involving Azure Blob Storage.
+
+**1. Set `techdocs.publisher.type` config in your `app-config.yaml`**
+
+Set `techdocs.publisher.type` to `'openStackSwift'`.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'openStackSwift'
+```
+
+**2. Create an Azure Blob Storage Container**
+
+Create a dedicated container for TechDocs sites.
+[Refer to the official documentation](https://docs.openstack.org/mitaka/user-guide/dashboard_manage_containers.html).
+
+TechDocs will publish documentation to this container and will fetch files from
+here to serve documentation in Backstage. Note that the container names are
+globally unique.
+
+Set the config `techdocs.publisher.openStackSwift.containerName` in your
+`app-config.yaml` to the name of the container you just created.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'openStackSwift'
+    openStackSwift:
+      containerName: 'name-of-techdocs-storage-container'
+```
+
+**3a. (Recommended) Authentication using environment variable**
+
+Set the config `techdocs.publisher.openStackSwift.accountName` in
+your `app-config.yaml` to the your account name.
+
+The storage blob client will automatically use the environment variable
+`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` to authenticate with
+Azure Blob Storage.
+[Steps to create the service where the variables can be retrieved from](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal).
+
+https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad for more
+details.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'azureBlobStorage'
+    azureBlobStorage:
+      containerName: 'name-of-techdocs-storage-bucket'
+      credentials:
+        accountName:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME
+```
+
+**3b. Authentication using app-config.yaml**
+
+If you do not prefer (3a) and optionally like to use a service account, you can
+follow these steps.
+
+To get credentials, access the Azure Portal and go to "Settings > Access Keys",
+and get your Storage account name and Primary Key.
+https://docs.microsoft.com/en-us/rest/api/storageservices/authorize-with-shared-key
+for more details.
+
+```yaml
+techdocs:
+  publisher:
+    type: 'azureBlobStorage'
+    azureBlobStorage:
+      containerName: 'name-of-techdocs-storage-bucket'
+      credentials:
+        accountName:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_NAME
+        accountKey:
+          $env: TECHDOCS_AZURE_BLOB_STORAGE_ACCOUNT_KEY
+```
+
+**4. That's it!**
+
+Your Backstage app is now ready to use Azure Blob Storage for TechDocs, to store
+and read the static generated documentation files. When you start the backend of
+the app, you should be able to see
+`techdocs info Successfully connected to the Azure Blob Storage container` in
+the logs.