kopia lustrzana https://github.com/cloudflare/wildebeest
Reorganizing documentation
Celso Martinho
rodzic
4d7e37b4de
commit
54bb9696ae
223
README.md
223
README.md
|
|
@ -1,217 +1,34 @@
|
|||
# Wildebeest
|
||||
|
||||
|
||||
|
||||
Wildebeest is an [ActivityPub](https://www.w3.org/TR/activitypub/) and [Mastodon](https://joinmastodon.org/)-compatible server whose goal is to allow anyone to operate their Fediverse server and identity on their domain without needing to keep infrastructure, with minimal setup and maintenance, and running in minutes.
|
||||
|
||||
Wildebeest runs on top Cloudflare's [Supercloud](https://blog.cloudflare.com/welcome-to-the-supercloud-and-developer-week-2022/), uses [Workers](https://workers.cloudflare.com/) and [Pages](https://pages.cloudflare.com/), the [D1 database](https://developers.cloudflare.com/d1/) to store metadata and configurations, [Zero Trust Access](https://www.cloudflare.com/en-gb/products/zero-trust/access/) to handle authentication and [Images](https://www.cloudflare.com/en-gb/products/cloudflare-images/) for media handling.
|
||||
Wildebeest runs on top Cloudflare's [Supercloud](https://blog.cloudflare.com/welcome-to-the-supercloud-and-developer-week-2022/), uses [Workers](https://workers.cloudflare.com/), [Pages](https://pages.cloudflare.com/), [Durable Objects](https://developers.cloudflare.com/workers/learning/using-durable-objects/), [Queues](https://developers.cloudflare.com/queues/), the [D1 database](https://developers.cloudflare.com/d1/) to store metadata and configurations, [Zero Trust Access](https://www.cloudflare.com/en-gb/products/zero-trust/access/) to handle authentication and [Images](https://www.cloudflare.com/en-gb/products/cloudflare-images/) for media handling.
|
||||
|
||||
Currently, Wildebeest supports the following features:
|
||||
|
||||
- Authentication and automatic profile creation.
|
||||
- Message signing & notification.
|
||||
- Inbox and Outbox notes (text, mentions and images), follow, announce (reblog), accept (friend), like.
|
||||
- Server to server federation.
|
||||
- Web client for content exploration (read-only).
|
||||
- Compatibility with [other Mastodon clients](#supported-clients) (Mobile iOS/Android and Web).
|
||||
- [ActivityPub](https://www.w3.org/TR/activitypub/), [WebFinger](https://www.rfc-editor.org/rfc/rfc7033), [NodeInfo](https://github.com/cloudflare/wildebeest/tree/main/functions/nodeinfo), [WebPush](https://datatracker.ietf.org/doc/html/rfc8030) and [Mastodon-compatible](https://docs.joinmastodon.org/api/) APIs. Wildebeest can connect to or receive connections from other Fediverse servers.
|
||||
- Compatible with the most popular Mastodon [web](https://github.com/nolanlawson/pinafore) (like [Pinafore](https://github.com/nolanlawson/pinafore)), desktop, and [mobile clients](https://joinmastodon.org/apps). We also provide a simple read-only web interface to explore the timelines and user profiles.
|
||||
- You can publish, edit, boost, or delete posts, sorry, toots. We support text, images, and (soon) video.
|
||||
- Anyone can follow you; you can follow anyone.
|
||||
- You can search for content.
|
||||
- You can register one or multiple accounts under your instance. Authentication can be email-based on or using any Cloudflare Access compatible IdP, like GitHub or Google.
|
||||
- You can edit your profile information, avatar, and header image.
|
||||
|
||||
Cloudflare will continue to evolve this open-source project with additional features over time and listen to the community feedback to steer our priorities. Pull requests and issues are welcome too.
|
||||
|
||||
## Requirements
|
||||
Please read our [announcement blog](https://blog.cloudflare.com/welcome-to-wildebeest-the-fediverse-on-cloudflare/) for more details on how we built Wildebeest.
|
||||
|
||||
Wildebeest is a full-stack app running on top of Cloudflare Pages using [Pages Functions](https://developers.cloudflare.com/pages/platform/functions/). We are of course assuming that you have a Cloudflare account (click [here](https://dash.cloudflare.com/sign-up) if you don't) and have at least one [zone](https://www.cloudflare.com/en-gb/learning/dns/glossary/dns-zone/) using Cloudflare. If you don't have a zone, you can use [Cloudflare Registrar](https://www.cloudflare.com/en-gb/products/registrar/) to register new a new domain or [transfer](https://developers.cloudflare.com/registrar/get-started/transfer-domain-to-cloudflare/) an existing one.
|
||||
## Tutorial
|
||||
|
||||
Some features, like data persistence, access controls, media storage, are handled by other Cloudflare products:
|
||||
Follow this tutorial to deploy Wildebeest:
|
||||
|
||||
- [D1](https://developers.cloudflare.com/d1/) for the database.
|
||||
- [Workers KV](https://developers.cloudflare.com/workers/learning/how-kv-works/) for object caching.
|
||||
- [Zero Trust Access](https://www.cloudflare.com/en-gb/products/zero-trust/access/) to handle user authentication and SSO on [any identity provider](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/).
|
||||
- [Images](https://www.cloudflare.com/en-gb/products/cloudflare-images/) for media handling.
|
||||
- [Requirements](docs/requirements.md)
|
||||
- [Getting started](docs/getting-started.md)
|
||||
- [Access policy](docs/access-policy.md)
|
||||
- [Supported clients](docs/supported-clients.md)
|
||||
- [Updating Wildebeest](docs/updating.md)
|
||||
- [Other Cloudflare services](docs/other-services.md)
|
||||
- [Troubleshooting](docs/troubleshooting.md)
|
||||
|
||||
Most of our products offer a [generous free plan](https://www.cloudflare.com/en-gb/plans/) that allows our users to try them for personal or hobby projects that aren’t business-critical. However the **_Images_** one doesn't have a free tier, so for setting up your instance you need to activate one of the paid **_Images_** plans.
|
||||
|
||||
### Images plan
|
||||
|
||||
To activate **_Images_**, please login into your account, select **_Images_** on the left menu, and then select the plan that best fits your needs.
|
||||
|
||||
|
||||
|
||||
### API token
|
||||
|
||||
Before we begin, you also need to create an API token in your Cloudflare account. To do that, [login](https://dash.cloudflare.com/) into your account, and press the **_Create Token_** button under **_My Profile (top right corner) / API Tokens_**.
|
||||
|
||||
|
||||
|
||||
Now press **_Create Custom Token_** and add the following permissions:
|
||||
|
||||
- D1, account level, edit permission.
|
||||
- Cloudflare Pages, account level, edit permission.
|
||||
- Access: Apps and policies, account level, edit permission.
|
||||
- Access: Organizations, Identity Providers and Groups, account level, read permission.
|
||||
- Workers KV Storage, account level, edit permission.
|
||||
- DNS, zone level, edit permission.
|
||||
- Cloudflare Images, account level, edit permission.
|
||||
- Workers Scripts, account level, edit permission.
|
||||
|
||||
|
||||
|
||||
You can limit the token to the specific zone where you will using Wildebeest if you want. Don't set a TTL.
|
||||
|
||||
Now **_Continue to Summary_**, review your settings, and **_Create Token_**. Take note of your token and store it in your password manager, you're going to need it later.
|
||||
|
||||
### Zone and Account IDs
|
||||
|
||||
You also need to take note of your Zone and Account IDs. To find them, [login](https://dash.cloudflare.com/) into your account and select the zone (domain) where you plan to use Wildebeest. Then, on the **_Overview_** page you will the following information:
|
||||
|
||||
|
||||
|
||||
We're all set now, let's start the installation process.
|
||||
|
||||
## Getting started
|
||||
|
||||
Wildebeest uses [Deploy to Workers](https://deploy.workers.cloudflare.com/) to automate the installation process.
|
||||
|
||||
**Click here to start the installation.**
|
||||
|
||||
[<img src="https://deploy.workers.cloudflare.com/button"/>](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/wildebeest&authed=true&fields={%22name%22:%22Zone%20ID%22,%22secret%22:%22CF_ZONE_ID%22,%22descr%22:%22Get%20your%20Zone%20ID%20from%20the%20Cloudflare%20Dashboard%22}&fields={%22name%22:%22Domain%22,%22secret%22:%22CF_DEPLOY_DOMAIN%22,%22descr%22:%22Domain%20on%20which%20your%20instance%20will%20be%20running%22}&fields={%22name%22:%22Instance%20title%22,%22secret%22:%22INSTANCE_TITLE%22,%22descr%22:%22Title%20of%20your%20instance%22}&fields={%22name%22:%22Administrator%20Email%22,%22secret%22:%22ADMIN_EMAIL%22,%22descr%22:%22An%20Email%20address%20that%20can%20be%20messaged%20regarding%20inquiries%20or%20issues%22}&fields={%22name%22:%22Instance%20description%22,%22secret%22:%22INSTANCE_DESCR%22,%22descr%22:%22A%20short,%20plain-text%20description%20of%20your%20instance%22})
|
||||
|
||||
Please pay attention to all the steps involved in the installation process.
|
||||
|
||||
- Authorize Workers to use your GitHub account.
|
||||
- Enter your **Account ID** (from the previous section) and the **API token** that you created previously.
|
||||
- Configure your instance/project with the **Zone ID**, **Domain**, **Title**, **Admin Email** and **Description**.
|
||||
- Fork the repository into your personal GitHub account.
|
||||
- Enable GitHub Actions.
|
||||
- Deploy.
|
||||
|
||||
### Authorizations and API Token
|
||||
|
||||
The first two steps are authorizing Workers to use your GitHub account and entering your **Account ID** and the **API token** you created in the requirements section.
|
||||
|
||||
|
||||
|
||||
### Instance configuration
|
||||
|
||||
Configure your instance/project with the **Zone ID** (see the requirements above), **Domain** (the full FQDN domain of your zone, where you want to deploy your Wildebeest server), **Title**, **Admin Email** and **Description**.
|
||||
|
||||
|
||||
|
||||
Now click **_Fork the repository_**.
|
||||
|
||||
Then enable GitHub Actions and confirm by clicking **_Workflows enabled_**.
|
||||
|
||||
And finally click **_Deploy_**.
|
||||
|
||||
|
||||
|
||||
The installation script will now build and deploy your project to Cloudflare Pages and will run a [Terraform script](https://github.com/cloudflare/wildebeest/blob/main/tf/main.tf) to configure the D1, KV, DNS, Images and Access settings automatically for you.
|
||||
|
||||
## Finish installation
|
||||
|
||||
If you followed all the steps, you should see a successful GitHub Actions build.
|
||||
|
||||
|
||||
|
||||
You can also confirm in the Cloudflare [dashboard](https://dash.cloudflare.com) that the Pages project, DNS entry, KV namespace, D1 database and Access rule were all created and configured.
|
||||
|
||||
Almost there, only one last step missing:
|
||||
|
||||
### Configure the access rule
|
||||
|
||||
The installation process automatically created a [Zero Trust Access application](https://developers.cloudflare.com/cloudflare-one/applications/) called `wildebeest-your-github-user` for you. Now you need to create a [policy](https://developers.cloudflare.com/cloudflare-one/policies/) that defines who can have access to your Wildebeest instance.
|
||||
|
||||
Go to https://one.dash.cloudflare.com/access and select your account, then select **_Access / Applications_** and Edit the `wildebeest-your-github-user` application.
|
||||
|
||||
|
||||
|
||||
Now click **_Add a policy_**. Name the policy `wildebeest-policy`, set the action to **_Allow_**, and add an include rule with the list of Emails that you want to allow and then click **_Save policy_**
|
||||
|
||||
|
||||
|
||||
### You're ready
|
||||
|
||||
Open your browser and go to your newly deployed Wildebeest domain `https://social.example/` (replace social.example with your domain). You should see something like this:
|
||||
|
||||
|
||||
|
||||
|
||||
Go to `https://social.example/api/v1/instance` (replace social.example with your domain) and double-check your configuration. It should show:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Private Mastodon Server",
|
||||
"email": "admin@social.example",
|
||||
"title": "My Wildebeest Server",
|
||||
"registrations": false,
|
||||
"version": "4.0.2",
|
||||
"rules": [],
|
||||
"uri": "social.example",
|
||||
"short_description": "Private Mastodon Server"
|
||||
}
|
||||
```
|
||||
|
||||
That's it, you're ready to start using your Wildebeest Mastodon compatible instance.
|
||||
|
||||
## Supported clients
|
||||
|
||||
Wildebeest is Mastodon API compatible, which means that you should be able to use most of the Web, Desktop, and Mobile clients with it. However, this project is a work in progress, and nuances might affect some of their functionality.
|
||||
|
||||
This is the list clients that we have been using successfully while developing and testing Wildebeest:
|
||||
|
||||
- [Pinafore](https://pinafore.social/) web client ([source](https://github.com/nolanlawson/pinafore)).
|
||||
- Mastodon [official](https://joinmastodon.org/apps) mobile client for [iOS](https://apps.apple.com/us/app/mastodon-for-iphone/id1571998974) ([source](https://github.com/mastodon/mastodon-ios)) and [Android](https://play.google.com/store/apps/details?id=org.joinmastodon.android) ([source](https://github.com/mastodon/mastodon-android)).
|
||||
|
||||
Wildebeest also provides a read-only web client in your instance URL, where you can explore the timelines (local and federated), posts and profiles. Please use the existing Mastodon clients to post and manage your account.
|
||||
|
||||
### Wildebeest has no user registration
|
||||
|
||||
Wildebeest uses [Zero Trust Access](https://www.cloudflare.com/en-gb/products/zero-trust/access/) to handle user authentication. It assumes that your users will register with another identity provider (Zero Trust supports [many providers](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/) or your custom one that implements [Generic SAML 2.0](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/generic-saml/)).
|
||||
|
||||
When you start using Wildebeest with a client, you don't need to register. Instead, you go straight to log in, which will redirect you to the Access page and handle the authentication step according to the policy that you defined earlier.
|
||||
|
||||
When authenticated, Access will redirect you back to Wildebeest. The first time this happens, we will detect that we don't have information about the user and ask for your **Username** and **Display Name**. This will be asked only once and is what will show in your public Mastodon profile.
|
||||
|
||||
|
||||
|
||||
## Updating Wildebeest
|
||||
|
||||
Updating your Wildebeest to the latest version is as easy as going to your forked repo on GitHub and clicking the **_Sync fork_** button:
|
||||
|
||||
|
||||
|
||||
Once your fork is syncronized with the official repo, the GitHub Actions CI is triggered and a new build will be deployed.
|
||||
|
||||
## Additional Cloudflare services
|
||||
|
||||
Since Wildebeest is a Cloudflare app running on Pages, you can seamlessly enable additional Cloudflare services to protect or improve your server.
|
||||
|
||||
### Email Routing
|
||||
|
||||
If you want to receive Email at your @social.example domain, you can enable [Email Routing](https://developers.cloudflare.com/email-routing/get-started/enable-email-routing/) for free and take advantage of sophisticated Email forwarding and protection features. Simply log in to your account, select the Wildebeest zone and then click on Email to enable.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Sometimes things go south. The GitHub Actions deployment can fail for some reason, or some configuration changed or was accidentally removed.
|
||||
|
||||
### Starting over
|
||||
|
||||
If you attempted to deploy Wildebeest in your account and something failed, or you simply want to reinstall everything from scratch again, you need to do manual checkups and cleaning before you start over.
|
||||
|
||||
- Go to your zone DNS settings and delete the CNAME record that points to `wildebeest-username.pages.dev`
|
||||
- Go to your account Pages section and delete the `wildebeest-username` project (make sure you remove the custom domain first if it's been configured).
|
||||
- Go to your account Workers / KV section and delete the `wildebeest-username-cache` and `wildebeest-terraform-username-state` namespaces.
|
||||
- Go to your account Workers / D1 and delete the `wildebeest-username` database.
|
||||
- Launch [Zero Trust](https://one.dash.cloudflare.com/), select your account, go to Access / Applications and delete the `wildebeest-username` application.
|
||||
- Delete your GitHub wildebeest forked repo.
|
||||
|
||||
You can now start a clean install.
|
||||
|
||||
### Error 1102
|
||||
|
||||
Wildebeest runs cryptographical functions and can process lots of data internally, depending on the size of the instance and social graph. It's possible that, in some cases, a request exceeds the Worker's resource limits in the free plan.
|
||||
|
||||
We will keep optimizing our code to run as fast as possible, but if you start seeing 1102 errors when using your Wildebeest pages and APIs, you might need to upgrade to Workers Unbound, which provides much higher limits.
|
||||
|
||||
To do that, go to your **_Account Page_** / **_Pages_**, select the `wildebeest-username` project, go to **_Settings_** / **_Functions_** and change the usage model to **Unbound**.
|
||||
|
||||
|
||||
|
||||
After you change your Pages project to Unbound, you need to redeploy it. Go to GitHub Actions in your repo, select the latest successful deploy, and press **Re-run all jobs**.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,51 @@
|
|||
[Index](../) ┊ [Back](getting-started.md) ┊ [Supported clients](supported-clients.md)
|
||||
|
||||
## Access Policy
|
||||
|
||||
### Wildebeest has no user registration
|
||||
|
||||
Wildebeest uses [Zero Trust Access](https://www.cloudflare.com/en-gb/products/zero-trust/access/) to handle user authentication. It assumes that your users will register with another identity provider (Zero Trust supports [many providers](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/) or your custom one that implements [Generic SAML 2.0](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/generic-saml/)).
|
||||
|
||||
When you start using Wildebeest with a client, you don't need to register. Instead, you go straight to log in, which will redirect you to the Access page and handle the authentication step according to the policy that you defined earlier.
|
||||
|
||||
When authenticated, Access will redirect you back to Wildebeest. The first time this happens, we will detect that we don't have information about the user and ask for your **Username** and **Display Name**. This will be asked only once and is what will show in your public Mastodon profile.
|
||||
|
||||
|
||||
|
||||
### Configure your access policy
|
||||
|
||||
The installation process automatically created a [Zero Trust Access application](https://developers.cloudflare.com/cloudflare-one/applications/) called `wildebeest-your-github-user` for you. Now you need to create a [policy](https://developers.cloudflare.com/cloudflare-one/policies/) that defines who can have access to your Wildebeest instance.
|
||||
|
||||
Go to https://one.dash.cloudflare.com/access and select your account, then select **_Access / Applications_** and Edit the `wildebeest-your-github-user` application.
|
||||
|
||||
|
||||
|
||||
Now click **_Add a policy_**. Name the policy `wildebeest-policy`, set the action to **_Allow_**, and add an include rule with the list of Emails that you want to allow and then click **_Save policy_**
|
||||
|
||||
|
||||
|
||||
### You're ready
|
||||
|
||||
Open your browser and go to your newly deployed Wildebeest domain `https://social.example/` (replace social.example with your domain). You should see something like this:
|
||||
|
||||
|
||||
|
||||
|
||||
Go to `https://social.example/api/v1/instance` (replace social.example with your domain) and double-check your configuration. It should show:
|
||||
|
||||
```json
|
||||
{
|
||||
"description": "Private Mastodon Server",
|
||||
"email": "admin@social.example",
|
||||
"title": "My Wildebeest Server",
|
||||
"registrations": false,
|
||||
"version": "4.0.2",
|
||||
"rules": [],
|
||||
"uri": "social.example",
|
||||
"short_description": "Private Mastodon Server"
|
||||
}
|
||||
```
|
||||
|
||||
That's it, you're ready to start using your Wildebeest Mastodon compatible instance.
|
||||
|
||||
[Index](../) ┊ [Back](getting-started.md) ┊ [Supported clients](supported-clients.md)
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
[Index](../) ┊ [Back](requirements.md) ┊ [Access policy](access-policy.md)
|
||||
|
||||
## Getting started
|
||||
|
||||
Before we start you need to take note of your Zone and Account IDs. To find them, [login](https://dash.cloudflare.com/) into your account and select the zone (domain) where you plan to use Wildebeest. Then, on the **_Overview_** page you will see something like this:
|
||||
|
||||
|
||||
|
||||
Take note, you need this information later. Let's start the installation process.
|
||||
|
||||
Wildebeest uses [Deploy to Workers](https://deploy.workers.cloudflare.com/) to automate the installation process.
|
||||
|
||||
**Click here to start the installation.**
|
||||
|
||||
[<img src="https://deploy.workers.cloudflare.com/button"/>](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/wildebeest&authed=true&fields={%22name%22:%22Zone%20ID%22,%22secret%22:%22CF_ZONE_ID%22,%22descr%22:%22Get%20your%20Zone%20ID%20from%20the%20Cloudflare%20Dashboard%22}&fields={%22name%22:%22Domain%22,%22secret%22:%22CF_DEPLOY_DOMAIN%22,%22descr%22:%22Domain%20on%20which%20your%20instance%20will%20be%20running%22}&fields={%22name%22:%22Instance%20title%22,%22secret%22:%22INSTANCE_TITLE%22,%22descr%22:%22Title%20of%20your%20instance%22}&fields={%22name%22:%22Administrator%20Email%22,%22secret%22:%22ADMIN_EMAIL%22,%22descr%22:%22An%20Email%20address%20that%20can%20be%20messaged%20regarding%20inquiries%20or%20issues%22}&fields={%22name%22:%22Instance%20description%22,%22secret%22:%22INSTANCE_DESCR%22,%22descr%22:%22A%20short,%20plain-text%20description%20of%20your%20instance%22}&apiTokenTmpl=[{%22key%22:%22d1%22,%22type%22:%22edit%22},{%22key%22:%22page%22,%22type%22:%22edit%22},{%22key%22:%22images%22,%22type%22:%22edit%22},{%22key%22:%22access%22,%22type%22:%22edit%22},{%22key%22:%22workers_kv_storage%22,%22type%22:%22edit%22},{%22key%22:%22access_acct%22,%22type%22:%22read%22},{%22key%22:%22dns%22,%22type%22:%22edit%22},{%22key%22:%22workers_scripts%22,%22type%22:%22edit%22},{%22key%22:%22account_rulesets%22,%22type%22:%22edit%22}]&apiTokenName=Wildebeest)
|
||||
|
||||
Please pay attention to all the steps involved in the installation process.
|
||||
|
||||
- Authorize Workers to use your GitHub account.
|
||||
- Enter your **Account ID** (from the previous section)
|
||||
- Press the **Create token** button first, to create it, it will redirect you to a token template with all the required permissions pre-configured. Then rnter the **API token** in the form.
|
||||
- Enter the **Zone ID**, **Domain**, **Title**, **Admin Email** and **Description** for your instance.
|
||||
- Fork the repository into your personal GitHub account.
|
||||
- Enable GitHub Actions.
|
||||
- Deploy.
|
||||
|
||||
Here is each step again, with screenshots:
|
||||
|
||||
### Authorizations and API Token
|
||||
|
||||
The first steps are authorizing Workers to use your GitHub account and entering your **Account ID**, pressing the **Create token** button and pasting the token in the **API Token** field.
|
||||
|
||||
|
||||
|
||||
### Instance configuration
|
||||
|
||||
Here we configure the instance/project with the **Zone ID**, **Domain** (the full FQDN domain of your zone, where you want to deploy your Wildebeest server), **Title**, **Admin Email** and **Description**.
|
||||
|
||||
|
||||
|
||||
Now click **_Fork the repository_**.
|
||||
|
||||
Then enable GitHub Actions and confirm by clicking **_Workflows enabled_**.
|
||||
|
||||
And finally click **_Deploy_**.
|
||||
|
||||
|
||||
|
||||
The installation script will now build and deploy your project to Cloudflare Pages and will run a [Terraform script](https://github.com/cloudflare/wildebeest/blob/main/tf/main.tf) to configure D1, Workers, DNS, Images and Access settings automatically for you.
|
||||
|
||||
Make sure the deploy was successful by looking at the GitHub Actions logs. If it wasn't, take a look at errors, we did our best trying to make then clear.
|
||||
|
||||
## Finish installation
|
||||
|
||||
If you followed all the steps, you should see a successful GitHub Actions build.
|
||||
|
||||
|
||||
|
||||
You can also confirm in the Cloudflare [dashboard](https://dash.cloudflare.com) that the Pages project, DNS entry, KV namespace, D1 database and Access rule were all created and configured.
|
||||
|
||||
[Index](../) ┊ [Back](requirements.md) ┊ [Access policy](access-policy.md)
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
[Index](../) ┊ [Back](updating.md) ┊ [Troubleshooting](troubleshooting.md)
|
||||
|
||||
## Additional Cloudflare services
|
||||
|
||||
Since Wildebeest is a Cloudflare app running on Pages, you can seamlessly enable additional Cloudflare services to protect or improve your server.
|
||||
|
||||
### Protection
|
||||
|
||||
Once Wildebeest is up and running, you can protect it from bad traffic and malicious actors. Cloudflare offers you [DDoS](https://www.cloudflare.com/en-gb/ddos/), [WAF](https://www.cloudflare.com/en-gb/waf/), and [Bot Management](https://www.cloudflare.com/en-gb/products/bot-management/) protection out of the box at a click's distance.
|
||||
|
||||
### Analytics
|
||||
|
||||
Likewise, you'll get instant network and content delivery optimizations from our products and [analytics](https://www.cloudflare.com/en-gb/analytics/) on how your Wildebeest instance is performing and being used.
|
||||
|
||||
### Email Routing
|
||||
|
||||
If you want to receive Email at your @social.example domain, you can enable [Email Routing](https://developers.cloudflare.com/email-routing/get-started/enable-email-routing/) for free and take advantage of sophisticated Email forwarding and protection features. Simply log in to your account, select the Wildebeest zone and then click on Email to enable.
|
||||
|
||||
[Index](../) ┊ [Back](updating.md) ┊ [Troubleshooting](troubleshooting.md)
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
[Index](../) ┊ [Back](../) ┊ [Getting started](getting-started.md)
|
||||
|
||||
## Requirements
|
||||
|
||||
Wildebeest is a full-stack app running on top of Cloudflare Pages using [Pages Functions](https://developers.cloudflare.com/pages/platform/functions/). We are of course assuming that you have a Cloudflare account (click [here](https://dash.cloudflare.com/sign-up) if you don't) and have at least one [zone](https://www.cloudflare.com/en-gb/learning/dns/glossary/dns-zone/) using Cloudflare. If you don't have a zone, you can use [Cloudflare Registrar](https://www.cloudflare.com/en-gb/products/registrar/) to register new a new domain or [transfer](https://developers.cloudflare.com/registrar/get-started/transfer-domain-to-cloudflare/) an existing one.
|
||||
|
||||
Some features, like data persistence, access controls, media storage, are handled by other Cloudflare products:
|
||||
|
||||
- [D1](https://developers.cloudflare.com/d1/) for the database.
|
||||
- [Workers KV](https://developers.cloudflare.com/workers/learning/how-kv-works/) for terraform state storage.
|
||||
- [Durable Objects](https://developers.cloudflare.com/workers/learning/using-durable-objects/) for strong-consistency object caching.
|
||||
- [Queues](https://developers.cloudflare.com/queues/) for asyncronous jobs.
|
||||
- [Zero Trust Access](https://www.cloudflare.com/en-gb/products/zero-trust/access/) to handle user authentication and SSO on [any identity provider](https://developers.cloudflare.com/cloudflare-one/identity/idp-integration/).
|
||||
- [Images](https://www.cloudflare.com/en-gb/products/cloudflare-images/) for media handling.
|
||||
|
||||
Most of our products offer a [generous free plan](https://www.cloudflare.com/en-gb/plans/) that allows our users to try them for personal or hobby projects that aren’t business-critical, however you will need a few paid subscriptions before you can use Wildebeest. These subscriptions are not specific to your Wildebeest instance, you can use them freely, manage them in the dashboard, or use them with other Workers projects.
|
||||
|
||||
- You need to subscribe one of the paid [Images](https://developers.cloudflare.com/images/cloudflare-images/) plans. Login into your account, select select **_Images_** on the left menu, and then select the plan that best fits your needs. The lowest $5/month plan will give 100,000 images of storage capacity.
|
||||
- You need to subscribe Workers Unbound. To do that, go to your account page and select **_Workers_** > **_Overview_** > **_Default Usage Model_** > **_Change_** and [chose](https://developers.cloudflare.com/workers/platform/pricing/#default-usage-model) Unbound. Make sure your Pages project is using Unbound too, after you deploy it. Go to **_Pages_** > **_wildebeest-username_** > **_Settings_** > **_Functions_** and change the usage model to Unbound. The minimum $5/month Workers Paid plan has [plenty of room space](https://developers.cloudflare.com/workers/platform/limits/) for Wildebeest.
|
||||
|
||||
Because you subscribed a Workers Paid plan to use Unbound, you also get Durable Objects and Queues and no further action is required. Please refer to our [Workers limits](https://developers.cloudflare.com/workers/platform/limits/) and [Queues limits](https://developers.cloudflare.com/queues/limits/) pages for more information. Queues requires the Workers Paid plan to use, but [does not increase](https://developers.cloudflare.com/queues/pricing/) your monthly subscription cost.
|
||||
|
||||
[Index](../) ┊ [Back](../) ┊ [Getting started](getting-started.md)
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
[Index](../) ┊ [Back](access-policy.md) ┊ [Updating Wildebeest](updating.md)
|
||||
|
||||
## Supported Clients
|
||||
|
||||
Wildebeest is Mastodon API compatible, which means that you should be able to use most of the Web, Desktop, and Mobile clients with it. However, this project is a work in progress, and nuances might affect some of their functionality.
|
||||
|
||||
This is the list clients that we have been using successfully while developing and testing Wildebeest:
|
||||
|
||||
- [Pinafore](https://pinafore.social/) web client ([source](https://github.com/nolanlawson/pinafore)).
|
||||
- Mastodon [official](https://joinmastodon.org/apps) mobile client for [iOS](https://apps.apple.com/us/app/mastodon-for-iphone/id1571998974) ([source](https://github.com/mastodon/mastodon-ios)) and [Android](https://play.google.com/store/apps/details?id=org.joinmastodon.android) ([source](https://github.com/mastodon/mastodon-android)).
|
||||
|
||||
Wildebeest also provides a read-only web client in your instance URL, where you can explore the timelines (local and federated), posts and profiles. Please use the existing Mastodon clients to post and manage your account.
|
||||
|
||||
[Index](../) ┊ [Back](access-policy.md) ┊ [Updating Wildebeest](updating.md)
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
[Index](../) ┊ [Back](other-services.md)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Sometimes things go south. The GitHub Actions deployment can fail for some reason, or some configuration changed or was accidentally removed.
|
||||
|
||||
### Starting over
|
||||
|
||||
If you attempted to deploy Wildebeest in your account and something failed, or you simply want to reinstall everything from scratch again, you need to do manual checkups and cleaning before you start over.
|
||||
|
||||
- Go to your zone DNS settings and delete the CNAME record that points to `wildebeest-username.pages.dev`
|
||||
- Go to your account Pages section and delete the `wildebeest-username` project (make sure you remove the custom domain first if it's been configured).
|
||||
- Go to your account Workers section and delete the `wildebeest-do` and `wildebeest-consumer-username` workers.
|
||||
- Go to your account Workers / KV section and delete the `wildebeest-username-cache` and `wildebeest-terraform-username-state` namespaces.
|
||||
- Go to your account Workers / D1 and delete the `wildebeest-username` database.
|
||||
- Launch [Zero Trust](https://one.dash.cloudflare.com/), select your account, go to Access / Applications and delete the `wildebeest-username` application.
|
||||
- Go to https://deploy.workers.cloudflare.com/, open the site settings in your browser and delete all the cookies and local storage data.
|
||||
- Delete your GitHub wildebeest forked repo.
|
||||
|
||||
You can now start a clean install.
|
||||
|
||||
### Error 1102
|
||||
|
||||
Wildebeest runs cryptographical functions and can process lots of data internally, depending on the size of the instance and social graph. It's possible that, in some cases, a request exceeds the Worker's resource limits in the free plan.
|
||||
|
||||
We will keep optimizing our code to run as fast as possible, but if you start seeing 1102 errors when using your Wildebeest pages and APIs, you might need to upgrade to Workers Unbound, which provides much higher limits, as mentioned in the [requirements](requirements.md):
|
||||
|
||||
- Go to your **_Account Page_** / **_Pages_**, select the `wildebeest-username` project, go to **_Settings_** / **_Functions_** and change the usage model to **Unbound**.
|
||||
- Go to your **_Account Page_** / **_Workers_**, select the `wildebeest-do` project, go to **_Settings_** / **_General_** and change the usage model to **Unbound**. Do the same for the `wildebeest-consumer-username` project. Go to **_Account Page_** / **_Workers_** / **_Overview_** again and make sure the Default Usage Model is Unbound.
|
||||
|
||||
|
||||
|
||||
After you change your Pages project to Unbound, you need to redeploy it. Go to GitHub Actions in your repo, select the latest successful deploy, and press **Re-run all jobs**.
|
||||
|
||||
[Index](../) ┊ [Back](other-services.md)
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
[Index](../) ┊ [Back](supported-clients.md) ┊ [Other Cloudflare services](other-services.md)
|
||||
|
||||
## Updating Wildebeest
|
||||
|
||||
The deployment workflow runs automatically every time the main branch changes, so updating the Wildebeest is as easy as synchronizing the upstream official repository with the fork. You don't even need to use git commands for that; GitHub provides a convenient **_Sync fork_** button in the UI that you can simply click.
|
||||
|
||||
|
||||
|
||||
Once your fork is syncronized with the official repo, the GitHub Actions workflow is triggered and a new build will be deployed.
|
||||
|
||||
Updates are incremental and non-destructive. When the GitHub Actions workflow redeploys Wildebeest, we only make the necessary changes to your configuration and nothing else. You don't lose your data; we don't need to delete your existing configurations.
|
||||
|
||||
Data loss is not a problem either because D1 supports migrations. If we need to add a new column to a table or a new table, we don't need to destroy the database and create it again; we just apply the necessary SQL to that change.
|
||||
|
||||
|
||||
|
||||
[Index](../) ┊ [Back](supported-clients.md) ┊ [Other Cloudflare services](other-services.md)
|
||||
Ładowanie…
Reference in New Issue