Skip to content

Fediverser can be run with or without integration with Lemmy, but for most of its features depend on having a direct connection with a Lemmy database. This guide assumes that you already have a Lemmy instance deployed and you want to add Fediverser to it, in order to let your users register and sign-up using their Reddit credentials.

Pre-requisites

You must have a Reddit account in order to obtain a Reddit API Key.

Installation

Docker

The easiest/fastest way to get Lemmy running is by using docker. To make Fediverser work with it, we will basically take the existing "docker stack" and add some services of our own.

Create a fediverser.yml file and place next on the same folder as the docker-compose have for your Lemmy server with the following contents:

x-fediverser-web-service-envvars: &fediverser-service-envvars
  DJANGO_SETTINGS_MODULE: fediverser.services.base.settings
  FEDIVERSER_DATABASE_HOST: fediverser_postgres
  FEDIVERSER_DATABASE_NAME: fediverser
  FEDIVERSER_DATABASE_USER: fediverser
  FEDIVERSER_DATABASE_PASSWORD: {{ fediverser_postgres_password }}
  FEDIVERSER_SECRET_KEY: {{ fediverser_application_secret_key }}
  FEDIVERSER_PORTAL_OPEN_REGISTRATIONS: "true"
  FEDIVERSER_ROOT_URLCONF: fediverser.services.portal.urls
  FEDIVERSER_STATIC_ROOT: /var/fediverser/static
  FEDIVERSER_MEDIA_ROOT: /var/fediverser/media
  FEDIVERSER_BROKER_URL: redis://fediverser_broker:6379/0
  FEDIVERSER_CACHE_BACKEND: django_redis.cache.RedisCache
  FEDIVERSER_CACHE_LOCATION: redis://fediverser_cache:6379/0
  FEDIVERSER_REDDIT_CLIENT_ID: "{{ fediverser_reddit_client_id }}"
  FEDIVERSER_REDDIT_CLIENT_SECRET: "{{ fediverser_reddit_client_secret }}"
  FEDIVERSER_CONNECTED_LEMMY_INSTANCE: "{{ domain }}"
  FEDIVERSER_PORTAL_URL: "{{ fediverser_portal_url }}"


x-fediversed-lemmy-envvars: &fediverser-lemmy-envvars
  LEMMY_DATABASE_HOST: postgres
  LEMMY_DATABASE_PORT: "5432"
  LEMMY_DATABASE_NAME: lemmy
  LEMMY_DATABASE_USER: lemmy
  LEMMY_DATABASE_PASSWORD: {{ postgres_password }}

x-fediverser-service: &fediverser-service
  image: mushroomlabs/fediverser:latest

  depends_on: &fediverser-service-dependencies
    - fediverser_cache
    - fediverser_broker
    - fediverser_postgres

  environment: &fediverser-portal-envvars
    <<: [*fediverser-service-envvars, *fediverser-lemmy-envvars]

  volumes:
    - ./volumes/fediverser/static:/var/fediverser/static
    - ./volumes/fediverser/media:/var/fediverser/media


x-webapp: &fediverser-webservice
  command: poetry run uvicorn fediverser.services.base.asgi:application --port 80 --host 0.0.0.0 --reload --reload-dir=/app/fediverser --reload-include *.html

services:
  fediverser_postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: fediverser
      POSTGRES_PASSWORD: {{ fediverser_postgres_password }}
      POSTGRES_DB: fediverser
    volumes:
      - ./volumes/fediverser/database:/var/lib/postgresql/data


  fediverser_broker:
    image: redis:latest
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 30s
      retries: 50
    volumes:
      - ./volumes/fediverser/broker:/data


  fediverser_cache:
    image: redis:latest
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 30s
      retries: 50
    volumes:
      - ./volumes/fediverser/cache:/data

  fediverser_admin:
    <<: [*fediverser-service, *fediverser-webservice]
    environment:
      <<: *fediverser-service-envvars
      FEDIVERSER_ROOT_URLCONF: fediverser.services.admin.urls
    ports:
      - "10801:80"

  fediverser_portal:
    <<: [*fediverser-service, *fediverser-webservice]
    ports:
      - "10802:80"

  fediverser_celery:
    <<: *fediverser-service
    command: poetry run celery -A fediverser.services.base worker -l INFO -E

  fediverser_celerybeat:
    <<: *fediverser-service
    command: poetry run celery -A fediverser.services.base beat -l INFO -S django

  fediverser_init_migrate_db:
    <<: *fediverser-service
    restart: on-failure
    command: poetry run django-admin migrate

  fediverser_init_collect_static:
    <<: *fediverser-service
    restart: on-failure
    command: poetry run django-admin collectstatic --no-input

Replace the following values:

  • {{ fediverser_postgres_password }} with a secure password for the postgres database that will be used by fediverser
  • {{ fediverser_application_secret_key }} with a secure, long string. A recommended way to get such string is by running pwgen -ns 48 1.
  • {{ fediverser_reddit_client_id }} and {{ fediverser_reddit_client_secret }} with your Reddit API credentials
  • {{ fediverser_portal_url }} will be the complete url (not just the domain) of the public-facing "portal" service for fediverser.
  • {{ postgres_password }} with the password that you already have defined for your Lemmy database
  • {{ domain }} will be the domain of your Lemmy instance

To run the whole stack, you should execute:

docker-compose -f docker-compose.tml -f fediverser.yml up -d

Ansible

Nothing to see here, yet!

This section has not been properly documented yet. If you have any questions please ask on Lemmy. That will help us to know what parts of the documentation work should be prioritized.

Source

Nothing to see here, yet!

This section has not been properly documented yet. If you have any questions please ask on Lemmy. That will help us to know what parts of the documentation work should be prioritized.

Post-installation steps

Configuration of nginx/proxy server

Nothing to see here, yet!

This section has not been properly documented yet. If you have any questions please ask on Lemmy. That will help us to know what parts of the documentation work should be prioritized.

The fediverser admin will be available on port 10801 and the portal site will be running on port 10802. You will need to change your nginx configuration so that it can serve requests to these ports.

Create admin user

The database for fediverser will be empty at first. You will need to register the user that can access the admins. This is achieved with the command poetry run django-admin createsuperuser. You will be prompted for username, password and email. The email is optional.

If you are running docker, don't forget that the you need to execute this from the docker container, so the command becomes docker-compose -f docker-compose.yml -f fediverser.yml exec -it poetry run django-admin createsuperuser