Merge pull request #81 from DefangLabs/postgres-docs

Postgres Docs

docs/concepts/configuration.md

@@ -23,14 +23,25 @@ defang config set API_KEY
 
 You can use sensitive config by specifying them in the `environment` section of a service in a `compose.yaml` file without any value, or by specifying an environment key with a `null` value in your Pulumi code.
 
-```ts
+```yaml
 services:
   service1:
     image: image1:latest
     environment:
       - API_KEY
 ```
 
+You can also use this syntax:
+
+
+```yaml
+services:
+  service1:
+    image: image1:latest
+    environment:
+      API_KEY:
+```
+
 Use the `defang config` command of the Defang CLI to manage the values.
 
 ## Connecting Services
@@ -45,4 +56,4 @@ You can find a sample of how to set sensitive config values [here](https://githu
 
 Here are the different ways sensitive config values are stored depending on the provider you are using:
 
-    * [AWS](../providers/aws.md#secrets)
+    * [AWS](../providers/aws/aws.md#secrets)

docs/concepts/defang-byoc.md

@@ -21,7 +21,7 @@ Defang does run the Defang build service to build your container images, which t
 The Public Beta of the v1 Defang BYOC AWS Provider is released as of Feb 1 2024.
 :::
 
-Please read the [AWS Provider](../providers/aws.md) documentation for more details about how the AWS provider works and how to get started.
+Please read the [AWS Provider](../providers/aws/aws.md) documentation for more details about how the AWS provider works and how to get started.
 
 ## DigitalOcean
 

docs/concepts/managed-storage/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Managed Storage",
+  "position": 450,
+  "collapsible": true
+}

docs/concepts/managed-storage/managed-object-storage.md

@@ -0,0 +1,21 @@
+---
+title: Managed Object Storage
+description: Defang can help you provision managed Redis instances.
+sidebar_position: 3000
+---
+
+# Managed Object Storage
+
+:::info Not Yet Supported
+As of September 2024, Defang does not yet support managed Object Storage, but it is on our roadmap. If you are interested in Object Storage support, please vote on [this issue](https://github.com/DefangLabs/defang/issues/688).
+:::
+
+Managed Object Storage, like AWS S3, is a service that allows you to store and retrieve large amounts of data. Object storage is ideal for storing unstructured data like images, videos, and backups.
+
+## Current Support
+
+| Provider | Managed Object Storage |
+| --- | --- |
+| [Playground](/docs/providers/playground.md) | ❌ |
+| [AWS](/docs/providers/aws/aws.md) | ❌ |
+

docs/concepts/managed-storage/managed-postgres.md

@@ -0,0 +1,65 @@
+---
+title: Managed Postgres
+description: Defang can help you provision managed Postgres.
+sidebar_position: 1000
+---
+
+# Managed Postgres
+
+Postgres, or PostgreSQL, is an advanced open-source relational database system known for its robustness, extensibility, and compliance with SQL standards, making it a popular choice for complex applications requiring reliable data integrity and sophisticated querying capabilities.
+
+## Current Support
+
+| Provider | Managed Postgres |
+| --- | --- |
+| [Playground](/docs/providers/playground) | ❌ |
+| [AWS](/docs/providers/aws/aws.md#managed-postgres) | ✅ |
+
+## How to use Managed Postgres
+
+To use managed Postgres, in your `compose.yaml` file, use the `x-defang-postgres` extension to define your Postgres service. Adding the extension will tell Defang to provision a managed instance, rather than running Postgres as a service.
+
+### Required Configuration
+
+When using managed Postgres, you **must** set a password for the database using `defang config set POSTGRES_PASSWORD`. If you do not provide the password, the deployment will fail. You can can assign the password in the service's environment variables (to learn more about how this works, read about [configuration](../configuration.md)).
+
+### Optional Configuration
+
+You can also set the following environment variables to configure the managed Postgres instance:
+
+- `POSTGRES_USER`: The user for the managed Postgres instance. The default is `postgres`.
+- `POSTGRES_DB`: The database name for the managed Postgres instance. The default is `postgres`.
+
+### Connecting to Managed Postgres
+
+You can connect to the managed Postgres instance using the name of your service as the hostname, `POSTGRES_USER`, `POSTGRES_DB`, and `POSTGRES_PASSWORD` environment variables.
+
+### Example
+
+```yaml
+  app:
+    # [...]
+    environment:
+      POSTGRES_HOST: database
+      POSTGRES_USER: postgres
+      POSTGRES_DB: postgres
+      // highlight-start
+      # Note: by leaving the value empty, Defang will use the 
+      # value set using `defang config set POSTGRES_PASSWORD`
+      POSTGRES_PASSWORD:
+      // highlight-end
+  database:
+    image: postgres:15
+    x-defang-postgres: true
+    restart: unless-stopped
+    ports:
+      - mode: host
+        target: 5432
+    environment:
+      // highlight-start
+      # Note: by leaving the value empty, Defang will use the 
+      # value set using `defang config set POSTGRES_PASSWORD`
+      POSTGRES_PASSWORD:
+      // highlight-end
+
+```

docs/concepts/managed-storage/managed-redis.md

@@ -0,0 +1,30 @@
+---
+title: Managed Redis
+description: Defang can help you provision managed Redis instances.
+sidebar_position: 2000
+---
+
+# Managed Redis
+
+Redis is an in-memory data structure store widely used for caching, real-time analytics, and session management due to its high performance, low latency, and support for various data types. Defang can help you provision a managed Redis instance. 
+
+## Current Support
+
+| Provider | Managed Redis |
+| --- | --- |
+| [Playground](/docs/providers/playground.md#managed-redis) | ❌ |
+| [AWS](/docs/providers/aws/aws.md#managed-redis) | ✅ |
+
+## How to use Managed Redis
+
+To use managed Redis, in your `compose.yaml` file, use the `x-defang-redis` extension to define your Redis service. Adding the extension will tell Defang to provision a managed instance, rather than running Redis as a service. Defang will use the image tag to determine the version to provision from your cloud provider. Here's an example:
+
+```yaml
+cache:
+  image: redis:6.2
+  x-defang-redis: true
+  restart: unless-stopped
+  ports:
+    - mode: host
+      target: 6379
+```

docs/concepts/managed-storage/managed-storage.md

@@ -0,0 +1,10 @@
+---
+title: Managed Storage
+description: Defang can help you provision managed storage services.
+sidebar_position: 000
+---
+
+# Managed Storage
+
+Defang helps you provision the infrastructure you need to run your services. That infrastructure is designed to scale in and out without persistent storage, so you can build highly scalable services. But Defang can also help you provision managed services to store and persist your data, like [caches](./managed-redis.md), [databases](./managed-postgres.md), and [object storage](./managed-object-storage.md).
+

docs/providers/aws/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "AWS",
+  "position": 1000,
+  "collapsible": true
+}

docs/providers/aws.md → docs/providers/aws/aws.md

@@ -1,7 +1,7 @@
 ---
 title: AWS
 description: Defang allows you to easily create and manage full, scalable applications with AWS.
-sidebar_position: 010
+sidebar_position: 000
 ---
 
 # AWS
@@ -50,6 +50,14 @@ To deploy your services, the Defang CLI packages your code and uploads it to an
 
 The provider runs your workloads using ECS using Fargate. It provisions a VPC with public and private subnets, and deploys your services to the private subnets. It then provisions an Application Load Balancer (ALB) and routes traffic to your services.
 
+## Managed Storage
+
+Defang can help you provision [managed storage](/docs/concepts/managed-storage/managed-storage.md) services. The following managed storage services are supported on AWS:
+
+### Managed Postgres
+
+When using [Managed Postgres](/docs/concepts/managed-storage/managed-postgres.md), the Defang CLI provisions an RDS Postgres instance in your account.
+
 ### Managed Redis
 
-When using [Managed Redis](../concepts/managed-storage.md#managed-redis), the Defang CLI provisions an ElastiCache Redis cluster in your account.
+When using [Managed Redis](/docs/concepts/managed-storage/managed-redis.md), the Defang CLI provisions an ElastiCache Redis cluster in your account.

docs/providers/azure.md

@@ -1,7 +1,7 @@
 ---
 title: Azure
 description: Defang will allow you to easily create and manage full, scalable applications with Azure.
-sidebar_position: 100
+sidebar_position: 4000
 ---
 
 # Azure

docs/providers/digital-ocean/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "Digital Ocean",
+  "position": 2000,
+  "collapsible": true
+}

docs/providers/digital-ocean/digital-ocean.md

@@ -0,0 +1,11 @@
+---
+title: Digital Ocean
+description: Defang allows you to easily create and manage full, scalable applications with Digital Ocean.
+sidebar_position: 000
+---
+
+# Digital Ocean
+
+:::info
+V1 Defang BYOC Digital Ocean Provider is in private beta as of September 2024.
+:::

docs/providers/gcp.md

@@ -1,7 +1,7 @@
 ---
 title: GCP
 description: Defang will allow you to easily create and manage full, scalable applications with GCP.
-sidebar_position: 200
+sidebar_position: 3000
 ---
 
 # GCP

docs/providers/playground.md

@@ -1,7 +1,7 @@
 ---
 title: Playground
 description: The Defang Playground is a free tier that allows you to experiment with Defang.
-sidebar_position: 000
+sidebar_position: 0000
 ---
 
 The Defang Playground is a free tier that allows you to experiment with Defang. The Playground is a shared that cannot be used to run production workloads. The Playground is a great way to get started with Defang and to experiment with the Defang CLI.
@@ -10,9 +10,4 @@ This page highlights architectural considerations when deploying to the playgrou
 
 ## Overview
 
-Overall, the Defang Playground is very similar to deploying to your own cloud account. The Playground runs on a Defang-managed AWS account, so you can expect it to work similarly to deploying to [AWS](./aws.md).
-
-## Managed Redis
-
-The playground supports [Managed Redis](../concepts/managed-storage.md#managed-redis). Fundamentally, this works the same as it does in [AWS](./aws.md#managed-redis).
-
+Overall, the Defang Playground is very similar to deploying to your own cloud account. The Playground runs on a Defang-managed AWS account, so you can expect it to work similarly to deploying to [AWS](./aws/aws.md).