Deployment Guide Update

**NOTE** This is a resubmission of [PR elk-zone#1494](elk-zone#1494), which was inadvertently closed by a force-push - [X] Add Cloudflare Pages to deployment guide - [X] Refactor Netlify deployment guide - [X] Add Getting Started page to the deployment guide that covers topics that are common/shared by multiple deployment types - [X] Add cloudflare_pages.yml workflow file (set to workspace/manual trigger)
Distal-Labs · Mar 11, 2023 · 18de171 · 18de171
1 parent 70b3902
commit 18de171
Show file tree

Hide file tree

Showing 12 changed files with 396 additions and 61 deletions.
diff --git a/.github/workflows/cloudflare_pages.yml b/.github/workflows/cloudflare_pages.yml
@@ -0,0 +1,55 @@
+name: Deploy to Cloudflare Pages
+
+on:
+  # Uncomment *ONLY* this to enable CD for every new release
+  # push:
+  #   tags:
+  #     - 'v*'
+  # Uncomment *ONLY* this to enable CD for every push to the `main` branch
+  # push:
+  #   branch: release
+  workflow_dispatch: {}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: Production
+    permissions:
+      contents: read
+      deployments: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - run: corepack enable
+
+      - name: Set node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: pnpm
+
+      - name: Install build dependencies
+        run: npm install -g pnpm && pnpm i --frozen-lockfile
+
+      - name: Build Elk
+        run: pnpm run build
+        env:
+          HOST: 0.0.0.0
+          NODE_ENV: production
+          NUXT_DEPLOY_URL: ${{ vars.NUXT_DEPLOY_URL }}
+          NUXT_PUBLIC_DEFAULT_SERVER: ${{ vars.NUXT_PUBLIC_DEFAULT_SERVER }}
+          NUXT_STORAGE_DRIVER: kv-binding
+          VITE_DEV_PWA: true
+          NITRO_PRESET: cloudflare_pages
+
+      - name: Publish
+        uses: cloudflare/pages-action@1
+        with:
+          directory: .output/public
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: ${{ secrets.CLOUDFLARE_PAGES_PROJECT_NAME }}
+          apiToken: ${{ secrets.CLOUDFLARE_PAGES_API_TOKEN }}
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs/content/2.deployment/1.netlify.md b/docs/content/2.deployment/1.netlify.md
diff --git a/docs/content/2.deployment/10.getting_started.md b/docs/content/2.deployment/10.getting_started.md
@@ -0,0 +1,82 @@
+# Getting Started
+## Introduction
+
+Want to host Elk for your Mastodon instance? You came to the right place! This section covers topics that are common to several kinds of deployments, including:
+- [Preparing for deployment](#prerequisites)
+- [Obtaining the Elk source code](#creating-a-fork)
+- [Configuring persistent storage](#setting-up-cloudflare-workers-kv)
+
+
+## Prerequisites
+Before getting started, please ensure that you have access to the following:
+- If you don't have a GitHub account, [create one](https://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F&source=header-home) before proceeding. The _Free_ tier includes everything you need to deploy Elk.
+- If you plan to deploy Elk using serverless infrastructure (e.g. Netlify, Cloudflare Pages) _**or**_ intend to use continuous integration/continuous deployment tools (e.g. GitHub Actions), then you'll need a Cloudflare account in order to setup a [key-value store](https://www.cloudflare.com/products/workers-kv/) that will be used to save Elk application and user credentials. If you don't have a Cloudflare account, [create one](https://dash.cloudflare.com/sign-up/workers) before proceeding. The _Workers Free_ plan includes everything you need to deploy Elk and run a personal/low-traffic instance, **however**, you may incur charges if you [exceed plan limits](https://www.cloudflare.com/plans/developer-platform/) 
+
+![Cloudflare Workers Free plan limits as of February 19, 2023.](/docs/images/selfhosting-guide/cf-workers-limits.png)
+
+- If you plan to deploy Elk to a containerized environment, you'll need to provision a file system-based persistent storage and mount it as a volume. Please refer to [Docker's official documentation](https://docs.docker.com/engine/reference/commandline/volume_create/) and/or your hosting provider's product guide for detailed instructions on how to do this.
+
+<br>[back to top](#getting-started)
+
+## Creating a fork
+
+[Click here to fork the Elk repository](https://github.com/elk-zone/elk/fork). Make sure to _deselect_ "Copy the main branch only" so that you have access to the [`release`](https://github.com/elk-zone/elk/tree/release) branch, which is more stable than the [`main`](https://github.com/elk-zone/elk) branch. 
+
+
+![The settings to use for forking the Elk repository](/docs/images/selfhosting-guide/github-fork.png)
+
+For a more detailed guide to forking a repository, please refer to [GitHub's official documentation](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
+
+<br>[back to top](#getting-started)
+
+### Which branch(es) to deploy?
+
+> **_A note about alpha software:_** Elk is under active development. Many core features are ready for daily use, but many others remain a work-in-progress. Please be mindful of this fact as you consider which branch to deploy (and to which audiences). 
+
+<br>
+
+If you followed [these instructions](#creating-a-fork), you have access to 2 branches for your deployment: `release` and `main`. You can deploy one, or the other, or both. 
+
+If you're looking to Elk as a replacement for daily use, we strongly recommend sticking to the `release` branch. If you are a developer that likes to live on the cutting edge, even if that means dealing with feature regressions and new bugs, then the `main` branch will be more to your liking.
+
+Unless you're an experienced developer that's actively contributing to the Elk project, deploying any branch *other than* `release` and `main` is **_strongly discouraged_**; these other branches contain features in various stages of testing and development－ all of them have the potential to permanently corrupt or destroy data without warning. 
+
+If you're a developer that's interested in contributing to the Elk project, please review the [Contributing](https://github.com/elk-zone/elk/tree/release#-contributing) section on the repository's main landing page.
+
+<br>[back to top](#getting-started)
+
+## Setting up Cloudflare Workers KV
+### Create a KV Namespace
+As [mentioned earlier](#prerequisites), you'll need to create a Cloudflare KV Namespace if you are deploying Elk to a serverless environment, such as [Netlify Functions](https://www.netlify.com/products/#netlify-functions) or [Cloudflare Pages](https://pages.cloudflare.com/). The following instructions will guide you through the process by using the Cloudflare Dashboard:[^1]
+
+1. Log into your CloudFlare account.
+2. From the left navigation bar on the *main* account Dashboard (this is one navigation level _above_ the website-level dashboards):
+   - Click "Workers",
+     > _Note:_ if this is your first time opening this tab, CloudFlare will ask you to set up a free custom Cloudflare Workers subdomain. Follow the instructions to set up the domain. For the purposes of this guide, it doesn't matter what you choose as your subdomain (besides, you can change it later)
+
+   - Then, click "KV" in the navigation bar:
+
+   ![Where to find the Workers and KV Namespace links](/docs/images/selfhosting-guide/cf-nav-bar.png)
+
+3. Click the blue "Create namespace" button that will appear in the main body of the page. Follow the instructions to name the KV Namespace. For Elk's purposes, you can label the KV Namespace whatever you want, but Cloudflare will not allow you to change the label. Click "Add" then make a note of the newly-created KV Namespace **ID**
+
+![How to create a KV Namespace using the Cloudflare Dashboard](/docs/images/selfhosting-guide/cf-create-kv-namespace.png)
+
+<br>[back to top](#getting-started)
+
+### Find your account ID and create an API token
+If your hosting provider is _**not**_ Cloudflare, then you'll need to create an API token that will allow Elk to read and write to the newly-created KV Namespace.
+
+1. Again, from the left-side navigation bar on the *main* account Dashboard, click on "Workers"
+2. Halfway down the **right-side** navigation bar, you will see a gray box labeled, `Account ID`－ make a note of that value and save it for later. 
+3. Beneath `Account ID` field you will see a link to "API Tokens", click on that link and then click on the blue button labeled "Create Token" (or "Get started" if this is the first Custom Token you create in your account):
+4. Follow the directions to label and configure your API Token. For Elk's purposes, the only required permission is **Account | Workers KV Storage | Edit** :
+
+![The settings to use for the CloudFlare API token](/docs/images/selfhosting-guide/cf-api-token-settings.png)
+
+5. Save the newly made token in a safe spot and **DO NOT** add it to any file that you may (intentionally or unintentionally) commit to any GitHub repository. You may want to keep the tab open while you configure the rest of your deployment.
+
+<br>[back to top](#getting-started)
+
+
+[^1]: If you prefer using the command line, then please refer to [Cloudflare's official documentation](https://developers.cloudflare.com/workers/wrangler/workers-kv/)
diff --git a/docs/content/2.deployment/20.netlify.md b/docs/content/2.deployment/20.netlify.md
@@ -0,0 +1,41 @@
+# Netlify
+> 👋🏼 **Before you continue:** please read through the [Getting Started](10.getting_started.md) page as it contains important information that can help you avoid common gotchas. It also offers instructions to help you fork the Elk repository and to configure a Cloudflare KV namespace and an API token, which are prerequisites to the section below.
+--------------
+## Introduction
+This section covers the basics of deploying Elk to Netlify. This kind of deployment requires Cloudflare KV for persistent storage. Both companies offer a _Free Tier_ that should suffice for a small/personal instance.
+
+## Importing the Elk repo into Netlify
+
+On the main page of your Netlify dashboard, press the "Import from GitHub" button. Point it to your Elk fork.
+
+On the third page with Site settings, change the "Branch to deploy" to `release` if you wish. Press "Deploy site".
+
+That's one step done! Keep the tab open while we hop over to Cloudflare for a bit.
+
+## Setting the environment variables on Netlify
+
+On your project page, go to "Site settings", and open the "Environment variables" section.
+
+There are 5 environment variables to add.
+
+| Environment variable | What it is |
+|---|---|
+| NUXT_CLOUDFLARE_ACCOUNT_ID | This is your Cloudflare Account ID. You can find it in "Workers > Overview" |
+| NUXT_CLOUDFLARE_API_TOKEN | Put your Cloudflare API token here. |
+| NUXT_CLOUDFLARE_NAMESPACE_ID | This is your Cloudflare KV Namespace ID. Note: this is not the *label*/*name* of the KV Namespace, but the Cloudflare-generated ID assigned to it; you can find it under "Workers > KV" |
+| NUXT_STORAGE_DRIVER | This must be set to `cloudflare` for this kind of deployment |
+| NUXT_PUBLIC_DEFAULT_SERVER | This is the address of the Mastodon instance that will show up when a user visits your Elk deployment and is not logged in. If you don't make that variable, it will point to `m.webtoo.ls` by default. |
+| NUXT_PUBLIC_SINGLE_INSTANCE | If enabled it will disable signing in to servers other than the server specified in `NUXT_PUBLIC_DEFAULT_SERVER` |
+| NUXT_PUBLIC_PRIVACY_POLICY_URL | This is the URL to a web page with information on your privacy policy. |
+
+That's it! All that's left to do is...
+
+## Deploy Elk!
+On your project page open the Deploys tab, click on "Trigger deploy" and "Deploy site". In a few minutes Elk should be up and running!
+
+## Use a custom domain
+If you want to use a custom domain, go to "Domain settings" on your Netlify project page, and press "Add custom domain". If your domain is not bought from Netlify, it will ask you to add a CNAME record. Do that.
+
+Once the custom domain is added, you'll need to add an SSL/TLS certificate. At the bottom of the page press "Verify DNS configuration" and if it succeeds, press "Provision certificate". If that fails, you may need to wait some time until your DNS propagetes.
+
+And that's it! Enjoy your instance's Elk!