kopia lustrzana https://github.com/cloudflare/wildebeest
update readme to clarify installation (and also fix typos)
Dario Piotrowicz
rodzic
97b6a3f60f
commit
72d9a62258
109
README.md
109
README.md
|
|
@ -6,59 +6,59 @@ Wildebeest runs on top Cloudflare's [Supercloud](https://blog.cloudflare.com/wel
|
|||
|
||||
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).
|
||||
- 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).
|
||||
|
||||
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
|
||||
|
||||
Wildebeest is a full-stack app running on top of Cloudflare Pages using a [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.
|
||||
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 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.
|
||||
- [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.
|
||||
|
||||
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 need to activate one of the ***Images*** plans.
|
||||
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.
|
||||
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***.
|
||||
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:
|
||||
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.
|
||||
- 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
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:
|
||||
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:
|
||||
|
||||
|
||||
|
||||
|
|
@ -74,22 +74,23 @@ Click here to start the installation.
|
|||
|
||||
Please pay attention to all the steps involved in the installation process.
|
||||
|
||||
* Authorize Workers to use your Github account.
|
||||
* Enter the ***Account ID*** and the ***API token*** that you created previously.
|
||||
* The script will then fork this repo into your personal Github account.
|
||||
* Enable Github Actions
|
||||
* Create two secrets (CF_ZONE_ID and CF_DEPLOY_DOMAIN) under the Github Actions settings. **See section below for detailed intructions**.
|
||||
- Authorize Workers to use your Github account.
|
||||
- Enter your **Account ID** (from the previous section) and the **API token** that you created previously.
|
||||
- Fork the repository into your personal Github account.
|
||||
- Enable Github Actions.
|
||||
- Open a new tab to `https://github.com/your-username/wildebeest` and create two secrets (CF_ZONE_ID and CF_DEPLOY_DOMAIN) under your Github Repository Actions settings. **See section below for detailed instructions**.
|
||||
- Deploy.
|
||||
|
||||
The installation script will now build and deploy your project to Cloudflare Pages and a [Terraform script](https://github.com/cloudflare/wildebeest/blob/main/tf/main.tf) to configure the D1, KV, DNS and Access settings automatically for you.
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### Github Actions secrets
|
||||
|
||||
In the installation script above, after you ***Enable Github Actions***, you need to create two secrets under your forked repo ***Settings / Secrets / Actions***. They are:
|
||||
In the installation script above, after you **_Enable Github Actions_**, you need to create two secrets under your forked repo, by going to **_Settings / Secrets / Actions_** and clicking on the **_New repository secret_** button. They are:
|
||||
|
||||
* **CF_ZONE_ID** - Use the Zone ID that you got from the requirements above.
|
||||
* **CF_DEPLOY_DOMAIN** - The full FQDN domain where you want to deploy your Wildebeest server. Example: social.example.com
|
||||
- **CF_ZONE_ID** - Use the Zone ID that you got from the requirements above.
|
||||
- **CF_DEPLOY_DOMAIN** - The full FQDN domain where you want to deploy your Wildebeest server. Example: social.example.com
|
||||
|
||||
**This step is critical. If you miss it, your deployment will fail.**
|
||||
|
||||
|
|
@ -109,17 +110,17 @@ Almost there, only two last steps missing:
|
|||
|
||||
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 update the [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 edit the existing policy on the next screen.
|
||||
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 edit the existing policy on the next screen.
|
||||
|
||||
|
||||
|
||||
Add an include rule to the policy with the list of Emails that you want to allow and then click ***Save policy***
|
||||
Add an include rule to the policy with the list of Emails that you want to allow and then click **_Save policy_**
|
||||
|
||||
|
||||
|
||||
### Configure your server
|
||||
|
||||
Open your browser and go to your newly deployed Wildebeest domain `https://social.example.com/start-instance` (replace social.example.com with your domain). Fill in the title, administrator Email and description. Press ***Configure***.
|
||||
Open your browser and go to your newly deployed Wildebeest domain `https://social.example.com/start-instance` (replace social.example.com with your domain). Fill in the title, administrator Email and description. Press **_Configure_**.
|
||||
|
||||
|
||||
|
||||
|
|
@ -127,14 +128,14 @@ Go to `https://social.example.com/api/v1/instance` (replace social.example.com w
|
|||
|
||||
```json
|
||||
{
|
||||
"description": "My personal Wildebeest instance (powered by Cloudflare)",
|
||||
"email": "john@social.example.com",
|
||||
"title": "my fediverse",
|
||||
"registrations": false,
|
||||
"version": "4.0.2",
|
||||
"rules": [],
|
||||
"uri": "social.example.com",
|
||||
"short_description": "I can only show you the door, you're the one that has to walk through it"
|
||||
"description": "My personal Wildebeest instance (powered by Cloudflare)",
|
||||
"email": "john@social.example.com",
|
||||
"title": "my fediverse",
|
||||
"registrations": false,
|
||||
"version": "4.0.2",
|
||||
"rules": [],
|
||||
"uri": "social.example.com",
|
||||
"short_description": "I can only show you the door, you're the one that has to walk through it"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -146,12 +147,12 @@ Wildebeest is Mastodon API compatible, which means that you should be able to us
|
|||
|
||||
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)).
|
||||
- [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)).
|
||||
|
||||
Wilebeest also provides a read-only web client in your instance URL, where you can explore the timelines (local and federated), posts and profiles. We will continue to improve this web client and eventually add suport to posting content as well.
|
||||
Wildebeest also provides a read-only web client in your instance URL, where you can explore the timelines (local and federated), posts and profiles. We will continue to improve this web client and eventually add support for posting content as well.
|
||||
|
||||
## Aditional Cloudflare services
|
||||
## 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.
|
||||
|
||||
|
|
@ -167,11 +168,11 @@ Sometimes things go south. The GitHub Actions deployment can fail for some reaso
|
|||
|
||||
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.
|
||||
* Go to your account Workers / KV section and delete the `wildebeest-username-cache` namespace.
|
||||
* 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.
|
||||
- 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.
|
||||
- Go to your account Workers / KV section and delete the `wildebeest-username-cache` namespace.
|
||||
- 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.
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue