Browse Source

Add mkdocs configuration

main
Horst Gutmann 1 year ago
parent
commit
0484d06f43
No known key found for this signature in database GPG Key ID: 6F203F0D220F8E98
6 changed files with 96 additions and 59 deletions
  1. +2
    -1
      .gitignore
  2. +5
    -58
      README.md
  3. +11
    -0
      docs/_theme/css/custom.css
  4. +43
    -0
      docs/getting-started.md
  5. +19
    -0
      docs/index.md
  6. +16
    -0
      mkdocs.yml

+ 2
- 1
.gitignore View File

@ -8,4 +8,5 @@ node_modules
/frontend/yarn-error.log
/dist
/vendor
/webmentiond.yaml
/webmentiond.yaml
/site

+ 5
- 58
README.md View File

@ -11,63 +11,10 @@ This repository contains the source code for the Webmention backend used at
A public Docker image built automatically from the master branch of this
repository is available on <https://hub.docker.com/r/zerok/webmentiond>.
**Need help?** Please ask on [r/webmentiond](https://www.reddit.com/r/webmentiond/) or in our [GitHub issues](https://github.com/zerok/webmentiond/issues).
You can find a detailed getting started guide and lots of additional
documentation inside the [docs/](./docs/) folder!
## How to get started
1. You need to have an SMTP server through which the server can send you
e-mails. This is necessary in order to authenticate with the management UI.
Put the credentials for your SMTP account into the folowing environment
variables:
- `MAIL_HOST`
- `MAIL_PORT`
- `MAIL_USER`
- `MAIL_PASSWORD`
- `MAIL_FROM`
If you don't have a mailserver that supports TLS set the environment
variable `MAIL_NO_TLS` to `true`.
2. Pick an allowed e-mail address that can be used to log in and write it into
the `AUTH_ADMIN_EMAILS` environment variable.
3. Pick a secret key that should be used to sign the tokens generated by the
server and store that in the `AUTH_JWT_SECRET` environment variable.
Now that you have all that, start the server with the following command:
```
$ docker run --rm \
-e "MAIL_USER=${MAIL_USER}" \
-e "MAIL_PORT=${MAIL_PORT}" \
-e "MAIL_HOST=${MAIL_HOST}" \
-e "MAIL_PASSWORD=${MAIL_PASSWORD}" \
-e "MAIL_FROM=${MAIL_FROM}" \
-v ${PWD}/data:/data \
-p 8080:8080 \
zerok/webmentiond:latest \
--addr 0.0.0.0:8080 \
--auth-jwt-secret ${AUTH_JWT_SECRET} \
--auth-admin-emails ${AUTH_ADMIN_MAILS} \
--allowed-target-domains ${ALLOWED_TARGET_DOMAINS}
```
When you now go to http://localhost:8080/ui/ you will see a login dialog where
you can enter your admin e-mail address. For details on the authentication
flow, please take a look at the "Authentication flow" section below.
## Authentication flow
1. Go to `/ui/#/login`.
2. Enter your admin e-mail.
3. A token link is sent to you via e-mail.
4. Use this link to authenticate and receive a JWT that is then used by the
server.
## Further documentation
- [Policies](./docs/policies.md)
- [Configuration](./docs/configuration.md)
- [How to use FontAwesome Pro icons](./docs/fontawesome.md)
**Need help?** Please ask on
[r/webmentiond](https://www.reddit.com/r/webmentiond/) or in our [GitHub
issues](https://github.com/zerok/webmentiond/issues).

+ 11
- 0
docs/_theme/css/custom.css View File

@ -0,0 +1,11 @@
a {
color: #a11bd6;
}
a:hover {
color: #a11bd6;
}
.bg-primary {
background: #a11bd6;
background-color: #a11bd6 !important;
}

+ 43
- 0
docs/getting-started.md View File

@ -0,0 +1,43 @@
# Getting started
1. You need to have an SMTP server through which the server can send you
e-mails. This is necessary in order to authenticate with the management UI.
Put the credentials for your SMTP account into the folowing environment
variables:
- `MAIL_HOST`
- `MAIL_PORT`
- `MAIL_USER`
- `MAIL_PASSWORD`
- `MAIL_FROM`
If you don't have a mailserver that supports TLS set the environment
variable `MAIL_NO_TLS` to `true`.
2. Pick an allowed e-mail address that can be used to log in and write it into
the `AUTH_ADMIN_EMAILS` environment variable.
3. Pick a secret key that should be used to sign the tokens generated by the
server and store that in the `AUTH_JWT_SECRET` environment variable.
Now that you have all that, start the server with the following command:
```
$ docker run --rm \
-e "MAIL_USER=${MAIL_USER}" \
-e "MAIL_PORT=${MAIL_PORT}" \
-e "MAIL_HOST=${MAIL_HOST}" \
-e "MAIL_PASSWORD=${MAIL_PASSWORD}" \
-e "MAIL_FROM=${MAIL_FROM}" \
-v ${PWD}/data:/data \
-p 8080:8080 \
zerok/webmentiond:latest \
--addr 0.0.0.0:8080 \
--auth-jwt-secret ${AUTH_JWT_SECRET} \
--auth-admin-emails ${AUTH_ADMIN_MAILS} \
--allowed-target-domains ${ALLOWED_TARGET_DOMAINS}
```
When you now go to http://localhost:8080/ui/ you will see a login dialog where
you can enter your admin e-mail address. For details on the authentication
flow, please take a look at the "Authentication flow" section below.

+ 19
- 0
docs/index.md View File

@ -0,0 +1,19 @@
# webmentiond
[webmentiond](https://github.com/zerok/webmentiond) is a little server
for receiving webmentions. It comes with the following features:
- A server for receiving mentions and storing them in a SQLite database
- A simple UI for managing incoming mentions, approving and rejecting them
A public Docker image built automatically from the master branch of
this repository is available on
<https://hub.docker.com/r/zerok/webmentiond>.
Curious? We've prepared a little [getting-started
guide](getting-started.md) for you 🙂
Need help? Please ask on
[r/webmentiond](https://www.reddit.com/r/webmentiond/) or in [our
GitHub issues](https://github.com/zerok/webmentiond/issues).

+ 16
- 0
mkdocs.yml View File

@ -0,0 +1,16 @@
site_name: webmentiond
repo_url: https://github.com/zerok/webmentiond
theme:
name: mkdocs
custom_dir: docs/_theme
extra_css:
- _theme/css/custom.css
nav:
- Home: "index.md"
- Getting started: "getting-started.md"
- Reference:
- "configuration.md"
- Guides:
- "install-from-archive.md"
- "fontawesome.md"
- "policies.md"

Loading…
Cancel
Save