Merge pull request #160 from DefangLabs/linda-one-click-deploy

Added 1-Click Deploy tutorial

Author: commit111

docs/concepts/configuration.md

@@ -45,6 +45,10 @@ Use the `defang config` command of the Defang CLI to manage the values.
 You can find a sample of how to set sensitive config values [here](https://github.com/DefangLabs/samples/tree/main/samples/nodejs-openai).
 :::
 
+:::info
+If you are using the [1-Click Deploy](/docs/tutorials/using-one-click-deploy) option, you can set sensitive config values as secrets in your GitHub repository and the action will automatically deploy them for you. [Learn how to manage config values with the Defang Github Action](https://github.com/DefangLabs/defang-github-action?tab=readme-ov-file#managing-config-values).
+:::
+
 ## Interpolation
 
 Environment variables are set within the `environment` section of a service in a `compose.yaml` file. Any variables declared here will become available within the service container.

docs/providers/playground.md

@@ -4,7 +4,7 @@ description: The Defang Playground is a free tier that allows you to experiment
 sidebar_position: 0000
 ---
 
-The Defang Playground is a free tier that allows you to experiment with Defang. The Playground is a shared environment that should not be used to run production workloads. The Playground is a great way to get started with Defang using "1-click deploy" or to experiment with the Defang CLI.
+The Defang Playground is a free deployment provider that allows you to experiment with Defang. The Playground is a shared environment that should not be used to run production workloads. The Playground is a great way to get started with Defang. You can even use [1-Click Deploy](/docs/tutorials/using-one-click-deploy) to try it out quickly or you can get started with the [Defang CLI](/docs/getting-started).
 
 This page highlights architectural considerations when deploying to the Playground and any differences you might encounter when deploying to the Playground versus deploying to your own cloud account.
 

docs/tutorials/adding-custom-one-click-deploy.md

@@ -0,0 +1,91 @@
+---
+title: Adding Custom 1-Click Deploy to Your App
+sidebar_position: 800
+description: Add a custom 1-Click Deploy link to deploy your own app. 
+---
+
+# Adding Custom 1-Click Deploy to Your App
+
+This tutorial will show you how to add a 1-Click Deploy link to deploy your app to the Defang Playground. A 1-Click Deploy link points to a special Defang URL. Clicking this link will trigger a deployment of a project to Defang. The link is often placed as a button in the `README.md` file of your project repository, and is the easiest way to allow anyone to deploy your app. 
+
+:::info
+If you are trying to use 1-Click Deploy with one of our [samples](https://defang.io/samples/), we have a separate tutorial on [how to use 1-Click Deploy](/docs/tutorials/using-one-click-deploy). 
+:::
+
+## Pre-requisites
+
+- A [GitHub](https://github.com/) repository for your project
+
+## Step 1 - Prepare Your App
+
+You will need a `compose.yaml` file in the root folder of your project to describe the services which will be deployed. Learn more about writing [Compose files](/docs/concepts/compose#example-of-a-compose-file).
+
+## Step 2 - Copy the GitHub Workflow
+ 
+In your project, add a new folder named `.github`, then add a folder `workflows` inside it, and copy the entire GitHub Workflow `deploy.yaml` file from [here](https://github.com/DefangLabs/samples/blob/main/starter-sample/.github/workflows/deploy.yaml) into the `workflows` folder. 
+ 
+If your app requires [configuration](/docs/concepts/configuration) (e.g. API keys, passwords, etc.), learn more about [managing config variables with the Defang GitHub Action](https://github.com/DefangLabs/defang-github-action). 
+
+You should have a `.yaml` file similar to the one below:
+```yaml
+name: Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    environment: playground
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - name: Checkout Repo
+      uses: actions/checkout@v4
+
+    - name: Deploy
+      uses: DefangLabs/[email protected]
+```
+
+## Step 3 - Get the Encoded URL
+
+You will need the encoded version of your project repository's URL. This will be used as a redirect for the 1-Click Deploy link. 
+
+1. Copy the URL of your repository's homepage. It should look something like the following:
+```
+https://github.com/<your-github-username>/<your-repo-name>
+```
+2. You can go online and paste the URL from the step above into a URL encoder tool of your choice. You should end up with an encoded URL, similar to the one shown below:
+
+```
+https%3A%2F%2Fgithub.com%2F<your-github-username>%2F<your-repo-name>
+```
+
+## Step 4 - Create the 1-Click Deploy Link
+
+You will need to create a 1-Click Deploy link with the following format: `https://portal.defang.dev/redirect?url=` + your encoded URL. This ensures that the user can get [logged in](/docs/concepts/authentication/) to Defang before they get redirected to clone your app for deployment. 
+
+:::tip
+Optionally, you can add `&name=<your-project-here>` to the end of the link if you'd like to suggest a name for the user to use for their deployment.
+:::
+
+The finished link should look similar to the one below:
+```
+https://portal.defang.dev/redirect?url=https%3A%2F%2Fgithub.com%2F<your-github-username>%2F<your-project-here>&name=<your-project-here>
+```
+
+Now you have a link for anyone to deploy your app to Defang, with just 1 click. 
+
+## Step 5 - Use the Link
+For example, you can add it as a link in a Markdown file:
+```
+[1-Click Deploy Link](https://portal.defang.dev/redirect?url=<your-encoded-url>&name=<your-project-here>)
+```
+Or perhaps you can add it to a button with your own styling:
+```
+[![1-click-deploy-button](https://defang.io/deploy-with-defang.png)](https://portal.defang.dev/redirect?url=<your-encoded-url>&name=<your-project-here>)
+```

docs/tutorials/using-one-click-deploy.md

@@ -0,0 +1,51 @@
+---
+title: Using 1-Click Deploy
+sidebar_position: 300
+description: Use 1-Click Deploy to easily deploy a sample to the Defang Playground. 
+---
+
+# Using 1-Click Deploy
+
+This tutorial will show you how to use Defang 1-Click Deploy to deploy a sample to the Defang Playground. 
+
+The 1-Click Deploy button is the easiest way for new users to deploy a sample project to the [Defang Playground](/docs/concepts/defang-playground). No CLI installation is required. 
+
+:::info
+To access the full range of features provided by Defang, we recommend using the [Defang CLI](/docs/getting-started).
+:::
+
+## Step 1 - Choose a Sample
+Head to our [list of samples](https://defang.io/#samples) and click a sample you want to deploy. Then, click on the button that says "1-Click Deploy".
+
+![one-click-deploy-button](/img/use-one-click-tutorial/one-click-deploy-button.png)
+
+:::info
+Alternatively, you can find the "1-Click Deploy" button located in the `README.md` file of each sample's GitHub repository. 
+
+![deploy-with-defang-button](/img/use-one-click-tutorial/deploy-with-defang-button.png)
+:::
+
+## Step 2 - Allow Permissions
+
+After you've clicked, you will be prompted to use GitHub to log in. Once you see a "Create a new repository" page appear, allow the sample repository to get cloned into your GitHub account. You can do this by clicking the green "Create repository" button at the bottom. 
+
+![create-repository](/img/use-one-click-tutorial/create-repository.png)
+
+## Step 3 - Wait for Deployment to Complete
+
+A Github Action workflow will automatically start running to install Defang and deploy the sample to the Defang Playground. You can see this by going into the "Actions" tab in your GitHub repository. 
+
+You can view the status of your deployment in the [Defang Portal](https://portal.defang.dev/), or by downloading the [Defang CLI](/docs/getting-started).  
+
+:::tip
+If you decide to make a commit later to a repository created from 1-Click Deploy, then the project will automatically get deployed again to Defang Playground.
+:::
+
+When it is completed, you can view your deployed app using the deployment link generated by Defang, which should appear similar to the format below:
+```
+https://<username>-<service-name>--<port>.defang.dev
+```
+
+### Configuration in 1-Click Deploy
+
+If the sample you chose requires setting configuration, such as API keys, you can set sensitive config values as secrets in your GitHub repository and the GitHub Action can automatically handle those values for you. [Learn how to manage config values with the Defang Github Action](https://github.com/DefangLabs/defang-github-action?tab=readme-ov-file#managing-config-values).