askiiart/microblog.pub
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
microblog.pub/README.md
Thomas Sileo ac7a87f22a Document the setup wizard
2019-04-22 10:52:32 +02:00

9.2 KiB
Raw Blame History

microblog.pub

microblog.pub

Build Status #microblog.pub on Matrix License Code style: black

A self-hosted, single-user, ActivityPub powered microblog.

Still in early development.

/!\ Note to adventurer

If you are running an instance with Celery/RabbitMQ, you will need to perform a migration.

Getting closer to a stable release, it should be the "last" migration.

Features

  • Implements a basic ActivityPub server (with federation)
    • Compatible with Mastodon and others (Pleroma, Hubzilla...)
    • Also implements a remote follow compatible with Mastodon instances
  • Exposes your outbox as a basic microblog
    • Support all content types from the Fediverse (Note, Article, Page, Video, Image, Question...)
  • Comes with an admin UI with notifications and the stream of people you follow
  • Allows you to attach files to your notes
    • Privacy-aware image upload endpoint that strip EXIF meta data before storing the file
  • No JavaScript, that's it. Even the admin UI is pure HTML/CSS
  • Easy to customize (the theme is written Sass)
    • mobile-friendly theme
    • with dark and light version
  • Microformats aware (exports h-feed, h-entry, h-cards, ...)
  • Exports RSS/Atom/JSON 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
  • Deployable with Docker (Docker compose for everything: dev, test and deployment)
  • Implements IndieAuth endpoints (authorization and token endpoint)
    • U2F support
    • You can use your ActivityPub identity to login to other websites/app
  • Focused on testing

ActivityPub

microblog.pub implements an ActivityPub server, it implements both the client to server API and the federated server to server API.

Activities are verified using HTTP Signatures or by fetching the content on the remote server directly.

User Guide

The easiest and recommended way to run microblog.pub in production is to use the provided docker-compose config.

First install Docker and Docker Compose. It's the only requirements, Python is not needed on the host system.

Note that all the generated data (config included) will be stored on the host (i.e. not in Docker) in config/ and data/.

Installation

$ git clone https://github.com/tsileo/microblog.pub
$ cd microblog.pub
$ make config

Deployment

To spawn the docker-compose project (running this command will also update microblog.pub to latest and restart the project it it's already running):

$ make run

Backup

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). It should be safe to copy the directory while the docker-compose is running.

Development

The project requires Python3.7+.

The most convenient way to hack on microblog.pub is to run the Python server on the host directly, and evetything else in Docker.

# One-time setup (in a new virtual env)
$ pip install -r requirements.txt
# Start MongoDB and poussetaches
$ make poussetaches
$ env POUSSETACHES_AUTH_KEY="<secret-key>" docker-compose -f docker-compose-dev.yml up -d
# Run the server locally
$ FLASK_DEBUG=1 MICROBLOGPUB_DEBUG=1 FLASK_APP=app.py POUSSETACHES_AUTH_KEY="<secret-key>" flask run -p 5005 --with-threads

API

Your admin API key can be found at config/admin_api_key.key.

ActivityPub API

GET /

Returns the actor profile, with links to all the "standard" collections.

GET /tags/:tag

Special collection that reference notes with the given tag.

GET /stream

Special collection that returns the stream/inbox as displayed in the UI.

User API

The user API is used by the admin UI (and requires a CSRF token when used with a regular user session), but it can also be accessed with an API key.

All the examples are using HTTPie.

POST /api/note/delete{?id}

Deletes the given note id (the note must from the instance outbox).

Answers a 201 (Created) status code.

You can pass the id via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/note/delete Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity

Response

{
    "activity": "https://microblog.pub/outbox/<delete_id>"
}

POST /api/note/pin{?id}

Adds the given note id (the note must from the instance outbox) to the featured collection (and pins it on the homepage).

Answers a 201 (Created) status code.

You can pass the id via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/note/pin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity

Response

{
    "pinned": true
}

POST /api/note/unpin{?id}

Removes the given note id (the note must from the instance outbox) from the featured collection (and un-pins it).

Answers a 201 (Created) status code.

You can pass the id via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/note/unpin Authorization:'Bearer <token>' id=http://microblob.pub/outbox/<note_id>/activity

Response

{
    "pinned": false
}

POST /api/like{?id}

Likes the given activity.

Answers a 201 (Created) status code.

You can pass the id via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/like Authorization:'Bearer <token>' id=http://activity-iri.tld

Response

{
    "activity": "https://microblog.pub/outbox/<like_id>"
}

POST /api/boost{?id}

Boosts/Announces the given activity.

Answers a 201 (Created) status code.

You can pass the id via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/boost Authorization:'Bearer <token>' id=http://activity-iri.tld

Response

{
    "activity": "https://microblog.pub/outbox/<announce_id>"
}

POST /api/block{?actor}

Blocks the given actor, all activities from this actor will be dropped after that.

Answers a 201 (Created) status code.

You can pass the id via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/block Authorization:'Bearer <token>' actor=http://actor-iri.tld/

Response

{
    "activity": "https://microblog.pub/outbox/<block_id>"
}

POST /api/follow{?actor}

Follows the given actor.

Answers a 201 (Created) status code.

You can pass the id via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/follow Authorization:'Bearer <token>' actor=http://actor-iri.tld/

Response

{
    "activity": "https://microblog.pub/outbox/<follow_id>"
}

POST /api/new_note{?content,reply}

Creates a new note. reply is the IRI of the "replied" note if any.

Answers a 201 (Created) status code.

You can pass the content and reply via JSON, form data or query argument.

Example

$ http POST https://microblog.pub/api/new_note Authorization:'Bearer <token>' content=hello

Response

{
    "activity": "https://microblog.pub/outbox/<create_id>"
}

GET /api/stream

Example

$ http GET https://microblog.pub/api/stream Authorization:'Bearer <token>'

Response

Contributions

PRs are welcome, please open an issue to start a discussion before your start any work.