From 8058d2bfd4e8db4543e24d4bcb46b79882c3fceb Mon Sep 17 00:00:00 2001 From: Manav Rathi Date: Fri, 8 Mar 2024 15:20:16 +0530 Subject: [PATCH 1/3] Add production deployments --- .github/workflows/web-deploy-accounts.yml | 43 +++++++++++++++++++++++ .github/workflows/web-deploy-auth.yml | 43 +++++++++++++++++++++++ .github/workflows/web-deploy-cast.yml | 43 +++++++++++++++++++++++ .github/workflows/web-deploy-photos.yml | 43 +++++++++++++++++++++++ web/docs/deploy-new.md | 25 +++++++++++-- 5 files changed, 195 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/web-deploy-accounts.yml create mode 100644 .github/workflows/web-deploy-auth.yml create mode 100644 .github/workflows/web-deploy-cast.yml create mode 100644 .github/workflows/web-deploy-photos.yml diff --git a/.github/workflows/web-deploy-accounts.yml b/.github/workflows/web-deploy-accounts.yml new file mode 100644 index 0000000000..8164aea441 --- /dev/null +++ b/.github/workflows/web-deploy-accounts.yml @@ -0,0 +1,43 @@ +name: "Deploy (accounts)" + +on: + push: + # Run workflow on pushes to the deploy/accounts + branches: [deploy/accounts] + +jobs: + deploy: + runs-on: ubuntu-latest + + defaults: + run: + working-directory: web + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Setup node and enable yarn caching + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "yarn" + cache-dependency-path: "docs/yarn.lock" + + - name: Install dependencies + run: yarn install + + - name: Build accounts + run: yarn build:accounts + + - name: Publish accounts + uses: cloudflare/pages-action@1 + with: + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + projectName: ente + branch: deploy/accounts + directory: web/apps/accounts/out + wranglerVersion: "3" diff --git a/.github/workflows/web-deploy-auth.yml b/.github/workflows/web-deploy-auth.yml new file mode 100644 index 0000000000..63a56b95be --- /dev/null +++ b/.github/workflows/web-deploy-auth.yml @@ -0,0 +1,43 @@ +name: "Deploy (auth)" + +on: + push: + # Run workflow on pushes to the deploy/auth + branches: [deploy/auth] + +jobs: + deploy: + runs-on: ubuntu-latest + + defaults: + run: + working-directory: web + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Setup node and enable yarn caching + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "yarn" + cache-dependency-path: "docs/yarn.lock" + + - name: Install dependencies + run: yarn install + + - name: Build auth + run: yarn build:auth + + - name: Publish auth + uses: cloudflare/pages-action@1 + with: + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + projectName: ente + branch: deploy/auth + directory: web/apps/auth/out + wranglerVersion: "3" diff --git a/.github/workflows/web-deploy-cast.yml b/.github/workflows/web-deploy-cast.yml new file mode 100644 index 0000000000..be4861c71f --- /dev/null +++ b/.github/workflows/web-deploy-cast.yml @@ -0,0 +1,43 @@ +name: "Deploy (cast)" + +on: + push: + # Run workflow on pushes to the deploy/cast + branches: [deploy/cast] + +jobs: + deploy: + runs-on: ubuntu-latest + + defaults: + run: + working-directory: web + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Setup node and enable yarn caching + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "yarn" + cache-dependency-path: "docs/yarn.lock" + + - name: Install dependencies + run: yarn install + + - name: Build cast + run: yarn build:cast + + - name: Publish cast + uses: cloudflare/pages-action@1 + with: + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + projectName: ente + branch: deploy/cast + directory: web/apps/cast/out + wranglerVersion: "3" diff --git a/.github/workflows/web-deploy-photos.yml b/.github/workflows/web-deploy-photos.yml new file mode 100644 index 0000000000..64a88421d3 --- /dev/null +++ b/.github/workflows/web-deploy-photos.yml @@ -0,0 +1,43 @@ +name: "Deploy (photos)" + +on: + push: + # Run workflow on pushes to the deploy/photos + branches: [deploy/photos] + +jobs: + deploy: + runs-on: ubuntu-latest + + defaults: + run: + working-directory: web + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + submodules: recursive + + - name: Setup node and enable yarn caching + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: "yarn" + cache-dependency-path: "docs/yarn.lock" + + - name: Install dependencies + run: yarn install + + - name: Build photos + run: yarn build:photos + + - name: Publish photos + uses: cloudflare/pages-action@1 + with: + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + projectName: ente + branch: deploy/photos + directory: web/apps/photos/out + wranglerVersion: "3" diff --git a/web/docs/deploy-new.md b/web/docs/deploy-new.md index 4686e17824..856175535b 100644 --- a/web/docs/deploy-new.md +++ b/web/docs/deploy-new.md @@ -6,8 +6,13 @@ how deployments happen on changes. The summary of what happens is: -* `docs/` get deployed to [help.ente.io](https://help.ente.io) whenever - something that changes `docs/` gets merged to main. +* Production deployments are triggered by pushing to the `deploy/*` branches. + +* [help.ente.io](https://help.ente.io) gets deployed whenever `docs/` changes on + main. + +* Every night, all the web apps are deployed to their nightly URLs using the + current code in main. This workflow can also be triggered manually. You likely don't need to know the rest of the details (until you do, but you can read on then). @@ -68,3 +73,19 @@ As a concrete example, the GitHub workflow that deploys `docs/` passes "help" as the branch name. The resulting deployment is available at "help.ente.pages.dev". Finally, we add a custom domain to point to it from [help.ente.io](https://help.ente.io). + +## Deployments + +| URL | Type |Deployment action | +|-----|------|------------------| +| [web.ente.io](https://web.ente.io) | Production | Push to `deploy/photos` | +| [photos.ente.io](https://photos.ente.io) | Production | Alias of [web.ente.io](https://web.ente.io) | +| [auth.ente.io](https://auth.ente.io) | Production | Push to `deploy/auth` | +| [accounts.ente.io](https://accounts.ente.io) | Production | Push to `deploy/accounts` | +| [cast.ente.io](https://cast.ente.io) | Production | Push to `deploy/cast` | +| [help.ente.io](https://help.ente.io) | Production | Push to `main` + changes in `docs/` | +| [TBD-photos.ente.io](https://photos.ente.sh) | Preview | Nightly deploy of `main` | +| [TBD-auth.ente.io](https://auth.ente.sh) | Preview | Nightly deploy of `main` | +| [TBD-accounts.ente.io](https://accounts.ente.sh) | Preview | Nightly deploy of `main` | +| [TBD-cast.ente.io](https://cast.ente.sh) | Preview | Nightly deploy of `main` | + From 0b585ce3a53013673d800065cbd52f64ff2bfdb6 Mon Sep 17 00:00:00 2001 From: Manav Rathi Date: Fri, 8 Mar 2024 15:38:06 +0530 Subject: [PATCH 2/3] Update the documentation --- web/docs/deploy-new.md | 91 ----------------------------- web/docs/deploy.md | 128 ++++++++++++++++++++++++++++------------- web/scripts/deploy.sh | 51 ---------------- 3 files changed, 87 insertions(+), 183 deletions(-) delete mode 100644 web/docs/deploy-new.md delete mode 100755 web/scripts/deploy.sh diff --git a/web/docs/deploy-new.md b/web/docs/deploy-new.md deleted file mode 100644 index 856175535b..0000000000 --- a/web/docs/deploy-new.md +++ /dev/null @@ -1,91 +0,0 @@ -# Deploying - -The various web apps and static sites in this repository are deployed on -Cloudflare Pages. This document describes details of how things were setup, and -how deployments happen on changes. - -The summary of what happens is: - -* Production deployments are triggered by pushing to the `deploy/*` branches. - -* [help.ente.io](https://help.ente.io) gets deployed whenever `docs/` changes on - main. - -* Every night, all the web apps are deployed to their nightly URLs using the - current code in main. This workflow can also be triggered manually. - -You likely don't need to know the rest of the details (until you do, but you can -read on then). - -## First time preparation - -Create a new Pages project in Cloudflare, setting it up to use [Direct -Upload](https://developers.cloudflare.com/pages/get-started/direct-upload/). - -> [!NOTE] -> -> Direct upload doesn't work for existing projects tied to your repository using -> the [Git -> integration](https://developers.cloudflare.com/pages/get-started/git-integration/). -> -> If you want to keep the pages.dev domain from an existing project, you should -> be able to delete your existing project and recreate it (assuming no one -> claims the domain in the middle). I've not seen this documented anywhere, but -> it worked when I tried, and it seems to have worked for [other people -> too](https://community.cloudflare.com/t/linking-git-repo-to-existing-cf-pages-project/530888). - - -There are two ways to create a new project, using Wrangler -[[1](https://github.com/cloudflare/pages-action/issues/51)] or using the -Cloudflare dashboard -[[2](https://github.com/cloudflare/pages-action/issues/115)]. Since this is one -time thing, the second option might be easier. - -The remaining steps are documented in [Cloudflare's guide for using Direct -Upload with -CI](https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/). -As a checklist, - -- Generate `CLOUDFLARE_API_TOKEN` -- Add `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` to the GitHub secrets -- Add your workflow. e.g. see `docs-deploy.yml`. - -This is the basic setup, and should already work. - -## Deploying multiple sites - -However, we wish to deploy multiple sites from this same repository, so the -standard Cloudflare conception of a single "production" branch doesn't work for -us. - -Instead, we tie each deployment to a branch name. Note that we don't have to -actually create the branch or push to it, this branch name is just used as the -the `branch` parameter that gets passed to `cloudflare/pages-action`. - -Since our root pages project is `ente.pages.dev`, so a branch named `foo` would -be available at `foo.ente.pages.dev`. - -Finally, we create CNAME aliases using a [Custom Domain in -Cloudflare](https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/) -to point to these deployments from our user facing DNS names. - -As a concrete example, the GitHub workflow that deploys `docs/` passes "help" as -the branch name. The resulting deployment is available at "help.ente.pages.dev". -Finally, we add a custom domain to point to it from -[help.ente.io](https://help.ente.io). - -## Deployments - -| URL | Type |Deployment action | -|-----|------|------------------| -| [web.ente.io](https://web.ente.io) | Production | Push to `deploy/photos` | -| [photos.ente.io](https://photos.ente.io) | Production | Alias of [web.ente.io](https://web.ente.io) | -| [auth.ente.io](https://auth.ente.io) | Production | Push to `deploy/auth` | -| [accounts.ente.io](https://accounts.ente.io) | Production | Push to `deploy/accounts` | -| [cast.ente.io](https://cast.ente.io) | Production | Push to `deploy/cast` | -| [help.ente.io](https://help.ente.io) | Production | Push to `main` + changes in `docs/` | -| [TBD-photos.ente.io](https://photos.ente.sh) | Preview | Nightly deploy of `main` | -| [TBD-auth.ente.io](https://auth.ente.sh) | Preview | Nightly deploy of `main` | -| [TBD-accounts.ente.io](https://accounts.ente.sh) | Preview | Nightly deploy of `main` | -| [TBD-cast.ente.io](https://cast.ente.sh) | Preview | Nightly deploy of `main` | - diff --git a/web/docs/deploy.md b/web/docs/deploy.md index 55d132da01..f02334bd9c 100644 --- a/web/docs/deploy.md +++ b/web/docs/deploy.md @@ -1,40 +1,42 @@ -# Deploying the web apps +# Deploying -## tl;dr; +The various web apps and static sites in this repository are deployed on +Cloudflare Pages. -```sh -yarn deploy:photos -``` +The summary of what happens is: -## Details +* Production deployments are triggered by pushing to the `deploy/*` branches. + Use the various `yarn deploy:*` commands to help with this. For example, `yarn + deploy:photos` will open a PR to merge the current `main` onto + `deploy/photos`, which'll trigger a deployment and deploy the code to + [web.ente.io](https://web.ente.io). -The various web apps (Ente Photos, Ente Auth) are deployed on Cloudflare Pages. +* [help.ente.io](https://help.ente.io) gets deployed whenever a PR that changes + anything inside `docs/` gets merged to `main`. -The deployment is done using the GitHub app provided by Cloudflare Pages. The -Cloudflare integration watches for pushes to all branches named "deploy/*". In -all cases, it runs the same script, `scripts/deploy.sh`, using the -`CF_PAGES_BRANCH` environment variable to decide what exactly to build ([CF -docs](https://developers.cloudflare.com/pages/how-to/build-commands-branches/)). +* Every night, all the web apps get automatically deployed to a nightly preview + URLs using the current code in main. This workflow can also be triggered + manually. -For each of these branches, we have configured CNAME aliases (Cloudflare calls -them Custom Domains) to give a stable URL to the deployments. +Here is a list of all the deployments, whether or not they are production +deployments, and the action that triggers them. -- `deploy/photos` → _web.ente.io_ -- `deploy/auth` → _auth.ente.io_ -- `deploy/accounts` → _accounts.ente.io_ -- `deploy/cast` → _cast.ente.io_ +| URL | Type |Deployment action | +|-----|------|------------------| +| [web.ente.io](https://web.ente.io) | Production | Push to `deploy/photos` | +| [photos.ente.io](https://photos.ente.io) | Production | Alias of [web.ente.io](https://web.ente.io) | +| [auth.ente.io](https://auth.ente.io) | Production | Push to `deploy/auth` | +| [accounts.ente.io](https://accounts.ente.io) | Production | Push to `deploy/accounts` | +| [cast.ente.io](https://cast.ente.io) | Production | Push to `deploy/cast` | +| [help.ente.io](https://help.ente.io) | Production | Push to `main` + changes in `docs/` | +| [TBD-photos.ente.io](https://photos.ente.sh) | Preview | Nightly deploy of `main` | +| [TBD-auth.ente.io](https://auth.ente.sh) | Preview | Nightly deploy of `main` | +| [TBD-accounts.ente.io](https://accounts.ente.sh) | Preview | Nightly deploy of `main` | +| [TBD-cast.ente.io](https://cast.ente.sh) | Preview | Nightly deploy of `main` | -Thus to trigger a, say, production deployment of the photos app, we can open and -merge a PR into the `deploy/photos` branch. Cloudflare will then build and -deploy the code to _web.ente.io_. +### Other subdomains -The command `yarn deploy:photos` just does that - it'll open a new PR to fast -forward the current main onto `deploy/photos`. There are similar `yarn deploy:*` -commands for the other apps. - -## Other subdomains - -Apart from this, there are also some subdomains: +Apart from this, there are also some other deployments: - `albums.ente.io` is a CNAME alias to the production deployment (`web.ente.io`). However, when the code detects that it is being served from @@ -44,22 +46,66 @@ Apart from this, there are also some subdomains: - `payments.ente.io` and `family.ente.io` are currently in a separate repositories (Enhancement: bring them in here). -## NODE_VERSION +--- +--- -In Cloudflare Pages setting the `NODE_VERSION` environment variables is defined. +The rest of the document describes details about how things were setup. You +likely don't need to know them to be able to deploy. -This determines which version of Node is used when we do `yarn build:foo`. -Currently this is set to `20.11.1`. The major version here should match that of -`@types/node` in our dev dependencies. +## First time preparation -It is a good idea to also use the same major version of node on your machine. -For example, for macOS you can install the the latest from the v20 series using -`brew install node@20`. +Create a new Pages project in Cloudflare, setting it up to use [Direct +Upload](https://developers.cloudflare.com/pages/get-started/direct-upload/). -## Adding a new app +> [!NOTE] +> +> Direct upload doesn't work for existing projects tied to your repository using +> the [Git +> integration](https://developers.cloudflare.com/pages/get-started/git-integration/). +> +> If you want to keep the pages.dev domain from an existing project, you should +> be able to delete your existing project and recreate it (assuming no one +> claims the domain in the middle). I've not seen this documented anywhere, but +> it worked when I tried, and it seems to have worked for [other people +> too](https://community.cloudflare.com/t/linking-git-repo-to-existing-cf-pages-project/530888). -1. Add a mapping in `scripts/deploy.sh`. -2. Add a [Custom Domain in - Cloudflare](https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/) - pointing to this branch's deployment. +There are two ways to create a new project, using Wrangler +[[1](https://github.com/cloudflare/pages-action/issues/51)] or using the +Cloudflare dashboard +[[2](https://github.com/cloudflare/pages-action/issues/115)]. Since this is one +time thing, the second option might be easier. + +The remaining steps are documented in [Cloudflare's guide for using Direct +Upload with +CI](https://developers.cloudflare.com/pages/how-to/use-direct-upload-with-continuous-integration/). +As a checklist, + +- Generate `CLOUDFLARE_API_TOKEN` +- Add `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` to the GitHub secrets +- Add your workflow. e.g. see `docs-deploy.yml`. + +This is the basic setup, and should already work. + +## Deploying multiple sites + +However, we wish to deploy multiple sites from this same repository, so the +standard Cloudflare conception of a single "production" branch doesn't work for +us. + +Instead, we tie each deployment to a branch name. Note that we don't have to +actually create the branch or push to it, this branch name is just used as the +the `branch` parameter that gets passed to `cloudflare/pages-action`. + +Since our root pages project is `ente.pages.dev`, so a branch named `foo` would +be available at `foo.ente.pages.dev`. + +Finally, we create CNAME aliases using a [Custom Domain in +Cloudflare](https://developers.cloudflare.com/pages/how-to/custom-branch-aliases/) +to point to these deployments from our user facing DNS names. + +As a concrete example, the GitHub workflow that deploys `docs/` passes "help" as +the branch name. The resulting deployment is available at "help.ente.pages.dev". +Finally, we add a custom domain to point to it from +[help.ente.io](https://help.ente.io). + diff --git a/web/scripts/deploy.sh b/web/scripts/deploy.sh deleted file mode 100755 index cbce135b91..0000000000 --- a/web/scripts/deploy.sh +++ /dev/null @@ -1,51 +0,0 @@ -#!/bin/sh - -# This script is run by the Cloudflare Pages integration when deploying the apps -# in this repository. The app to build is decided based on the value of the -# CF_PAGES_BRANCH environment variable. -# -# The Cloudflare Pages build configuration is set to use `out/` as the build -# output directory, so once we're done building we copy the app specific output -# to `out/` (symlinking didn't work). -# -# Ref: https://developers.cloudflare.com/pages/how-to/build-commands-branches/ -# -# To test this script locally, run -# -# CF_PAGES_BRANCH=deploy/foo ./scripts/deploy.sh -# - -set -o errexit -set -o xtrace - -if test "$(basename $(pwd))" != "web" -then - echo "ERROR: This script should be run from the web directory" - exit 1 -fi - -rm -rf out - -case "$CF_PAGES_BRANCH" in - deploy/accounts) - yarn build:accounts - cp -R apps/accounts/out . - ;; - deploy/auth) - yarn build:auth - cp -R apps/auth/out . - ;; - deploy/cast) - yarn build:cast - cp -R apps/cast/out . - ;; - deploy/photos) - yarn build:photos - cp -R apps/photos/out . - ;; - *) - echo "ERROR: We don't know how to build and deploy a branch named $CF_PAGES_BRANCH." - echo " Maybe you forgot to add a new case in web/scripts/deploy.sh" - exit 1 - ;; -esac From 25a04fbc5f32bd7177f2b298dd3fa85a101d3832 Mon Sep 17 00:00:00 2001 From: Manav Rathi Date: Fri, 8 Mar 2024 15:49:13 +0530 Subject: [PATCH 3/3] Update docs README --- docs/README.md | 39 +++++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/docs/README.md b/docs/README.md index 7af2291779..33eabbbb1d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,30 @@ Help and documentation for Ente's products > publishing these docs. They'll likely be available at help.ente.io once we > wrap those loose ends up. -## Running +## Quick edits + +You can edit these files directly on GitHub and open a pull request. +[help.ente.io](https://help.ente.io) will automatically get updated with your +changes in a few minutes after your pull request is merged. + +## Running locally + + +The above workflow is great since it doesn't require you to setup anything on +your local machine. But if you plan on contributing frequently, you might find +it easier to run everything locally. + +Clone this repository + +```sh +git clone https://github.com/ente-io/ente +``` + +Change to this directory + +```sh +cd ente/docs +``` Install dependencies @@ -22,16 +45,12 @@ Then start a local server yarn dev ``` -## Workflow +For an editor, VSCode is a good choice. Also install the Prettier extension for +VSCode, and set VSCode to format on save. This way the editor will automatically +format and wrap the text using the project's standard, so you can just focus on +the content. -You can edit these files directly on GitHub and open a pull request. That is the -easiest workflow to get started without needing to install anything on your -local machine. - -If you plan on contributing frequently, we recommend using an editor. VSCode is -a good choice. Also install the Prettier extension for VSCode, and set VSCode to -format on save. This way the editor will automatically format and wrap the text -using the project's standard, so you can just focus on the content. +## Have fun! Note that we currently don't enforce these formatting standards to make it easy for people unfamiliar with programming to also be able to make edits from GitHub