diff --git a/src/assets/images/workers/dtw-share-project.png b/src/assets/images/workers/dtw-share-project.png new file mode 100644 index 00000000000000..33c335076ca532 Binary files /dev/null and b/src/assets/images/workers/dtw-share-project.png differ diff --git a/src/assets/images/workers/dtw-user-flow.png b/src/assets/images/workers/dtw-user-flow.png new file mode 100644 index 00000000000000..7f64b1067d9c0d Binary files /dev/null and b/src/assets/images/workers/dtw-user-flow.png differ diff --git a/src/content/docs/workers/get-started/dashboard.mdx b/src/content/docs/workers/get-started/dashboard.mdx index 75d3c45499c09b..7f8fcaa1ab4e40 100644 --- a/src/content/docs/workers/get-started/dashboard.mdx +++ b/src/content/docs/workers/get-started/dashboard.mdx @@ -20,24 +20,43 @@ Follow this guide to create a Workers application using [the Cloudflare dashboar ## Setup -To create a Workers application: +To get started with a new Workers application: 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account. -2. Go to **Workers & Pages**. -3. Select **Create**. -4. Select a template or **Create Worker**. -5. Review the provided code and select **Deploy**. -6. Preview your Worker at its provided [`workers.dev`](/workers/configuration/routing/workers-dev/) subdomain. +2. Go to the **Workers & Pages** section of the dashboard. +2. Select [Create](https://dash.cloudflare.com/?to=/:account/workers-and-pages/create). From here, you can: + * You can select from the gallery of production-ready templates + * Import an existing Git repository on your own account + * Let Cloudflare clone and bootstrap a public repository containing a Workers application. +3. Once you've connected to your chosen [Git provider](/workers/ci-cd/builds/git-integration/github-integration/), configure your project and click `Deploy`. +4. Cloudflare will kick off a new build and deployment. Once deployed, preview your Worker at its provided `workers.dev` subdomain. -## Development +## Continue development +Applications started in the dashboard are set up with Git to help kickstart your development workflow. To continue developing on your repository, you can run: - +```bash +# clone you repository locally +git clone -## Next steps +# be sure you are in the root directory +cd +``` -To do more: +Now, you can preview and test your changes by [running Wrangler in your local development environment](/workers/local-development/). Once you are ready to deploy you can run: + +```bash +# adds the files to git tracking +git add . + +# commits the changes +git commit -m "your message" -- Push your project to a GitHub or GitLab respoitory then [connect to builds](/workers/ci-cd/builds/#get-started) to enable automatic builds and deployments. +# push the changes to your Git provider +git push origin main +``` + + +To do more: - Review our [Examples](/workers/examples/) and [Tutorials](/workers/tutorials/) for inspiration. - Set up [bindings](/workers/runtime-apis/bindings/) to allow your Worker to interact with other resources and unlock new functionality. - Learn how to [test and debug](/workers/testing/) your Workers. diff --git a/src/content/docs/workers/platform/deploy-buttons.mdx b/src/content/docs/workers/platform/deploy-buttons.mdx new file mode 100644 index 00000000000000..b9ab65e9a05099 --- /dev/null +++ b/src/content/docs/workers/platform/deploy-buttons.mdx @@ -0,0 +1,86 @@ +--- +title: Deploy to Cloudflare buttons +pcx_content_type: concept +sidebar: + order: 5 +head: [] +description: Set up a Deploy to Cloudflare button +--- + +import { Tabs, TabItem } from "@astrojs/starlight/components"; + +If you're building a Workers application and would like to share it with other developers, you can embed a Deploy to Cloudflare button in your README, blog post, or documentation to enable others to quickly deploy your application on their own Cloudflare account. Deploy to Cloudflare buttons eliminate the need for complex setup, allowing developers to get started with your public GitHub or GitLab repository in just a few clicks. + +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/staging/saas-admin-template) + +## What are Deploy to Cloudflare buttons? +Deploy to Cloudflare buttons simplify the deployment of a Workers application by enabling Cloudflare to: +* **Clone a Git repository**: Cloudflare clones your source repository into the user's GitHub/GitLab account where they can continue development after deploying. +* **Configure a project**: Your users can customize key details such as repository name, Worker name, and required resource names in a single setup page with customizations reflected in the newly created Git repository. +* **Build & deploy**: Cloudflare builds the application using [Workers Builds](/workers/ci-cd/builds) and deploys it to the Cloudflare network. Any required resources are automatically provisioned and bound to the Worker without additional setup. + +![Deploy to Cloudflare Flow](~/assets/images/workers/dtw-user-flow.png) + +## How to Set Up Deploy to Cloudflare buttons +Deploy to Cloudflare buttons can be embedded anywhere developers might want to launch your project. To add a Deploy to Cloudflare button, copy the following snippet and replace the Git repository URL with your project's URL. You can also optionally specify a subdirectory. + + + + +```md +[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=) +``` + + + +```html +Deploy to Cloudflare +``` + + + + +``` +https://deploy.workers.cloudflare.com/?url= +``` + + + +If you have already deployed your application using Workers Builds, you can generate a Deploy to Cloudflare button directly from the Cloudflare dashboard by selecting the share button (located within your Worker details) and copying the provided snippet. + +![Share an application](~/assets/images/workers/dtw-share-project.png) + +Once you have your snippet, you can paste this wherever you would like your button to be displayed. + +## Automatic Resource provisioning +If your Worker application requires Cloudflare resources, they will be automatically provisioned as part of the deployment. Currently, supported resources include: +* **Storage**: [KV namespaces](/kv/), [D1 databases](/d1/), [R2 buckets](/r2/), [Hyperdrive](/hyperdrive/), and [Vectorize databases](/vectorize/) +* **Compute**: [Durable Objects](/durable-objects/), [Workers AI](/workers-ai/), and [Queues](/queues/) + +Cloudflare will read the Wrangler configuration file of your source repo to determine resource requirements for your application. During deployment, Cloudflare will provision any necessary resources and update the Wrangler configuration where applicable for newly created resources (e.g. database IDs and namespace IDs). To ensure successful deployment, please make sure your source repository includes default values for resource names, resource IDs and any other properties for each binding. + +## Best practices +**Configuring Build/Deploy commands**: If you are using custom `build` and `deploy` scripts in your package.json (for example, if using a full stack framework or running D1 migrations), Cloudfare will automatically detect and pre-populate the build and deploy fields. Users can choose to modify or accept the custom commands during deployment configuration. + +If no `deploy` script is specified, Cloudflare will preconfigure `npx wrangler deploy` by default. If no `build` script is specified, Cloudflare will leave this field blank. + +**Running D1 Migrations**: If you would like to run migrations as part of your setup, you can specify this in your `package.json` by running your migrations as part of your `deploy` script. The migration command should reference the binding name rather than the database name to ensure migrations are successful when users specify a database name that is different from that of your source repository. The following is an example of how you can set up the scripts section of your `package.json`: + +```json +{ + "scripts": { + "build": "astro build", + "deploy": "npm run db:migrations:apply && wrangler deploy", + "db:migrations:apply": "wrangler d1 migrations apply DB_BINDING --remote" + } +} +``` + +## Limitations + +* **Monorepos**: Cloudflare does not fully support monorepos + * If your repository URL contains a subdirectory, your application must be fully isolated within that subdirectory, including any dependencies. Otherwise, the build will fail. Cloudflare treats this subdirectory as the root of the new repository created as part of the deploy process. + * Additionally, if you have a monorepo that contains multiple Workers applications, they will not be deployed together. You must configure a separate Deploy to Cloudflare button for each application. The user will manually create a distinct Workers application for each subdirectory. +* **Pages applications**: Deploy to Cloudflare buttons only support Workers applications. +* **Non-GitHub/GitLab repositories**: Source repositories from anything other than github.com and gitlab.com are not supported. Self-hosted versions of GitHub and GitLab are also not supported. +* **Private repositories**: Repositories must be public in order for others to successfully use your Deploy to Cloudflare button. \ No newline at end of file diff --git a/src/content/docs/workers/tutorials/deploy-button/index.mdx b/src/content/docs/workers/tutorials/deploy-button/index.mdx deleted file mode 100644 index 50b52e83d6bf23..00000000000000 --- a/src/content/docs/workers/tutorials/deploy-button/index.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -updated: 2023-08-01 -difficulty: Beginner -pcx_content_type: tutorial -title: Create a deploy button with GitHub Actions - ---- - -Deploy buttons let you deploy applications to Cloudflare's global network in under five minutes. The deploy buttons use Wrangler to deploy a Worker using the [Wrangler GitHub Action](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler). You can deploy an application from a set of ready-made Cloudflare templates, or make deploy buttons for your own applications to make sharing your work easier. - -Try the deploy button below to deploy a GraphQL server: - -[![Select Deploy with Workers to deploy a GraphQL server](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/workers-graphql-server) - -Refer to [deploy.workers.cloudflare.com](https://deploy.workers.cloudflare.com/) for additional projects to deploy. - -## Create a deploy button for your project - -1. Add a GitHub Actions workflow to your project. - -Add a new file to `.github/workflows`, such as `.github/workflows/deploy.yml`, and create a GitHub workflow for deploying your project. It should include a set of `on` events, including at least `repository_dispatch`, but probably `push` and maybe `schedule` as well. Add a step for publishing your project using [wrangler-action](https://github.com/cloudflare/wrangler-action): - -```yaml -name: Deploy Worker -on: - push: - pull_request: - repository_dispatch: -jobs: - deploy: - runs-on: ubuntu-latest - timeout-minutes: 60 - needs: test - steps: - - uses: actions/checkout@v2 - - name: Build & Deploy Worker - uses: cloudflare/wrangler-action@v3 - with: - apiToken: ${{ secrets.CF_API_TOKEN }} - accountId: ${{ secrets.CF_ACCOUNT_ID }} -``` - -2. Add the Markdown code for your button to your project's README, replacing the example `url` parameter with your repository URL. - -```md -[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/YOURUSERNAME/YOURREPO) -``` - -3. With your button configured, anyone can use the **Deploy with Workers** button in your repository README, and deploy their own copy of your application to Cloudflare's global network.