diff --git a/.github/workflows/web-deploy-accounts.yml b/.github/workflows/web-deploy-accounts.yml new file mode 100644 index 000000000..8164aea44 --- /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 000000000..63a56b95b --- /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 000000000..be4861c71 --- /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 000000000..64a88421d --- /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/docs/README.md b/docs/README.md index 7af229177..33eabbbb1 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 diff --git a/web/docs/deploy-new.md b/web/docs/deploy-new.md deleted file mode 100644 index 4686e1782..000000000 --- a/web/docs/deploy-new.md +++ /dev/null @@ -1,70 +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: - -* `docs/` get deployed to [help.ente.io](https://help.ente.io) whenever - something that changes `docs/` gets merged to main. - -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). diff --git a/web/docs/deploy.md b/web/docs/deploy.md index 55d132da0..f02334bd9 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 cbce135b9..000000000 --- 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