microblog.pub/README.md

125 lines
5.7 KiB
Markdown
Raw Normal View History

2018-05-18 13:41:41 -05:00
# microblog.pub
<p align="center">
<img
src="https://sos-ch-dk-2.exo.io/microblogpub/microblobpub.png"
width="200" height="200" border="0" alt="microblog.pub">
</p>
2019-06-29 04:36:21 -05:00
<p align="center">A self-hosted, single-user, <a href="https://activitypub.rocks">ActivityPub</a> powered microblog.</p>
2018-05-18 13:41:41 -05:00
<p align="center">
2019-04-11 15:09:31 -05:00
<a href="https://d.a4.io/tsileo/microblog.pub"><img src="https://d.a4.io/api/badges/tsileo/microblog.pub/status.svg" alt="Build Status"></a>
2018-06-27 16:27:48 -05:00
<a href="https://matrix.to/#/#microblog.pub:matrix.org"><img src="https://img.shields.io/badge/matrix-%23microblog.pub-blue.svg" alt="#microblog.pub on Matrix"></a>
2018-05-20 05:28:11 -05:00
<a href="https://github.com/tsileo/microblog.pub/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-AGPL_3.0-blue.svg?style=flat" alt="License"></a>
2019-04-13 03:01:55 -05:00
<a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
2018-05-18 13:41:41 -05:00
</p>
2019-06-29 04:35:37 -05:00
**Still in early development/I do not recommend to run an instance yet.**
2019-04-11 13:22:38 -05:00
2018-05-18 13:41:41 -05:00
## Features
- Implements a basic [ActivityPub](https://activitypub.rocks/) server (with federation)
2019-09-03 15:18:25 -05:00
- S2S (Server to Server) and C2S (Client to Server) protocols
- Compatible with [Mastodon](https://joinmastodon.org/) and others ([Pleroma](https://pleroma.social/), Misskey, Plume, PixelFed, Hubzilla...)
2018-05-20 05:28:11 -05:00
- Exposes your outbox as a basic microblog
2019-04-22 02:49:10 -05:00
- Support all content types from the Fediverse (`Note`, `Article`, `Page`, `Video`, `Image`, `Question`...)
2019-09-08 09:55:24 -05:00
- Markdown support
- Server-side code syntax highlighting
2019-09-03 15:59:49 -05:00
- Comes with an admin UI with notifications and the stream of people you follow
2019-09-03 15:18:25 -05:00
- Private "bookmark" support
- List support
2019-09-03 15:59:49 -05:00
- Allows you to attach files to your notes
2019-10-25 16:27:21 -05:00
- Custom emojis support
2019-09-03 15:18:25 -05:00
- Cares about your privacy
- The image upload endpoint strips EXIF meta data before storing the file
- Every attachment/media is cached (or proxied) by the server
2018-06-21 17:20:58 -05:00
- No JavaScript, **that's it**. Even the admin UI is pure HTML/CSS
2019-05-11 14:20:49 -05:00
- (well except for the Emoji picker within the admin, but it's only few line of hand-written JavaScript)
2018-05-18 13:41:41 -05:00
- Easy to customize (the theme is written Sass)
2018-05-25 16:57:29 -05:00
- mobile-friendly theme
- with dark and light version
2019-09-03 15:59:49 -05:00
- IndieWeb citizen
2019-09-03 15:18:25 -05:00
- Microformats aware (exports `h-feed`, `h-entry`, `h-cards`, ...)
2019-09-08 08:19:34 -05:00
- Export a feed in the HTML that is WebSub compatible
2019-10-25 16:27:21 -05:00
- Partial [Micropub](https://www.w3.org/TR/micropub/) support ([implementation report](https://micropub.rocks/implementation-reports/servers/416/s0BDEXZiX805btoa47sz))
2019-09-03 15:59:49 -05:00
- Implements [IndieAuth](https://indieauth.spec.indieweb.org/) endpoints (authorization and token endpoint)
2019-09-08 08:19:34 -05:00
- You can use your ActivityPub identity to login to other websites/app (with U2F support)
- Send [Webmentions](https://www.w3.org/TR/webmention/) to linked website (only for public notes)
- Exports RSS/Atom/[JSON](https://jsonfeed.org/) feeds
- You stream/timeline is also available in an (authenticated) JSON feed
- Comes with a tiny HTTP API to help posting new content and and read your inbox/notifications
2018-05-26 03:43:05 -05:00
- Deployable with Docker (Docker compose for everything: dev, test and deployment)
2018-06-21 17:20:58 -05:00
- Focused on testing
2019-09-03 15:18:25 -05:00
- Tested against the [official ActivityPub test suite](https://test.activitypub.rocks/), see [the results](https://activitypub.rocks/implementation-report/)
2019-04-15 14:32:58 -05:00
- [CI runs "federation" tests against two instances](https://d.a4.io/tsileo/microblog.pub)
2019-04-22 02:49:10 -05:00
- Project is running 2 up-to-date instances ([here](https://microblog.pub) and [there](https://a4.io))
2019-04-22 04:32:20 -05:00
- Manually tested against other major platforms
2019-04-22 02:49:10 -05:00
2018-05-18 13:41:41 -05:00
2019-04-22 03:52:32 -05:00
## User Guide
2019-04-22 04:27:42 -05:00
Remember that _microblog.pub_ is still in early development.
2019-04-22 03:52:32 -05:00
The easiest and recommended way to run _microblog.pub_ in production is to use the provided docker-compose config.
First install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/).
2019-04-22 04:03:48 -05:00
Python is not needed on the host system.
2019-04-22 03:52:32 -05:00
2019-04-22 04:03:48 -05:00
Note that all the generated data (config included) will be stored on the host (i.e. not only in Docker) in `config/` and `data/`.
2019-04-22 03:52:32 -05:00
2018-05-18 13:41:41 -05:00
### Installation
```shell
$ git clone https://github.com/tsileo/microblog.pub
$ cd microblog.pub
2019-04-22 03:52:32 -05:00
$ make config
2018-05-18 13:41:41 -05:00
```
2019-04-22 05:56:43 -05:00
Once the initial configuration is done, you can still tweak the config by editing `config/me.yml` directly.
2019-04-22 03:52:32 -05:00
### Deployment
2018-06-03 09:39:46 -05:00
2019-07-30 15:12:20 -05:00
To spawn the docker-compose project (running this command will also update _microblog.pub_ to latest and restart everything if it's already running):
2018-06-03 09:39:46 -05:00
2019-04-22 03:52:32 -05:00
```shell
$ make run
2018-05-18 13:41:41 -05:00
```
2019-04-22 05:56:43 -05:00
By default, the server will listen on `localhost:5005` (http://localhost:5005 should work if you're running locally).
For production, you need to setup a reverse proxy (nginx, caddy) to forward your domain to the local server
(and check [certbot](https://certbot.eff.org/) for getting a free TLS certificate).
2019-04-22 04:03:48 -05:00
### HTTP API
See [docs/api.md](docs/api.md) for the internal HTTP API documentation.
2019-04-22 05:56:43 -05:00
2019-04-22 03:52:32 -05:00
### Backup
2018-05-18 13:41:41 -05:00
2019-04-22 03:52:32 -05:00
The easiest way to backup all of your data is to backup the `microblog.pub/` directory directly (that's what I do and I have been able to restore super easily).
2019-04-22 04:27:42 -05:00
It should be safe to copy the directory while the Docker compose project is running.
2018-05-18 13:41:41 -05:00
2019-04-22 05:56:43 -05:00
2018-05-18 13:41:41 -05:00
## Development
2019-04-22 03:52:32 -05:00
The project requires Python3.7+.
2018-05-18 13:41:41 -05:00
2019-04-22 03:52:32 -05:00
The most convenient way to hack on _microblog.pub_ is to run the Python server on the host directly, and evetything else in Docker.
2018-05-18 13:41:41 -05:00
```shell
2019-04-22 03:52:32 -05:00
# One-time setup (in a new virtual env)
2018-05-18 13:41:41 -05:00
$ pip install -r requirements.txt
2019-04-15 14:32:58 -05:00
# Start MongoDB and poussetaches
$ make poussetaches
2019-04-22 03:52:32 -05:00
$ env POUSSETACHES_AUTH_KEY="<secret-key>" docker-compose -f docker-compose-dev.yml up -d
2018-05-18 13:41:41 -05:00
# Run the server locally
2019-04-22 03:52:32 -05:00
$ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_KEY="<secret-key>" flask run -p 5005 --with-threads
2018-05-18 13:41:41 -05:00
```
2018-06-01 13:29:44 -05:00
2018-05-18 13:41:41 -05:00
## Contributions
2019-04-22 04:27:42 -05:00
Contributions/PRs are welcome, please open an issue to start a discussion before your start any work.