beenull/ente
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[web] Add production deployment templates (#751)

Browse source 
Also update the documentation.
This commit is contained in:
Manav Rathi 2024-03-08 15:50:39 +05:30 committed by GitHub
commit bcb0e2fcc3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 288 additions and 172 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
.github/workflows/web-deploy-accounts.yml vendored Normal file
View file

@ -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"

43
.github/workflows/web-deploy-auth.yml vendored Normal file
View file

@ -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"

43
.github/workflows/web-deploy-cast.yml vendored Normal file
View file

@ -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"

43
.github/workflows/web-deploy-photos.yml vendored Normal file
View file

@ -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"

39
docs/README.md
View file

@ -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

70
web/docs/deploy-new.md
View file

@ -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).

128
web/docs/deploy.md
View file

@ -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).

51
web/scripts/deploy.sh
View file

@ -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