[opensourcedex]

Smithereen is a free, open source social networking project written in Java and released under Unlicense. It has 546 GitHub stars, 36 forks and 44 open issues, and was last pushed 9 hours ago. On this registry it ranks #42 of 44 tracked projects in Social Networking, with 5 head-to-head comparisons available.

What is Smithereen?

Smithereen is a federated, ActivityPub-compatible social network server written in Java that gives a self-hosted instance friends, walls, and groups, and it is aimed at administrators who want to run their own social space that talks to the wider fediverse rather than renting one from a platform.

What it is

Smithereen is an open-source social network server that implements ActivityPub, so an instance can follow, be followed by, and exchange posts with other federated services. It lives in the fediverse ecosystem and occupies the same slot as the general-purpose microblogging or social platforms that speak the same protocol, but it models a classic social network shape: a person has friends, a wall where posts appear, and membership in groups.

The concrete problem it solves is ownership of a social graph. Instead of putting an account, a friend list, and a group's history on someone else's infrastructure, an operator runs the server on their own hardware, holds the MySQL database and the uploaded media themselves, and still reaches the rest of the network over ActivityPub. It replaces the hosted social network account with an instance the operator controls, and it replaces a closed platform's group feature with federated groups that other servers can interact with.

Key capabilities

  • Implements ActivityPub federation, so posts and relationships travel between Smithereen instances and other fediverse software.
  • Provides friends, walls, and groups as first-class server concepts rather than bolted-on extras.
  • Ships an ./install.sh script that configures the server and creates the first account interactively.
  • Ships an ./update.sh script for upgrades, which accepts a custom installation directory and runs database migrations on first startup.
  • Uses config.properties for server configuration, with a commented example in examples/config.properties.
  • Supports either the local file system or S3-compatible object storage for user-uploaded media, configured through upload.s3.key_id and upload.s3.secret_key.
  • Includes example reverse-proxy configurations for nginx in examples/nginx.conf and Caddy in examples/Caddyfile, routing traffic to Smithereen and imgproxy.
  • Interface translations are managed through Crowdin, and project discussion happens in a Telegram chat.

Who uses it and how

  • Administrators running a single self-hosted instance on their own server, installing from a prebuilt CPU-specific release bundle and configuring the web server to proxy requests.
  • Operators who want uploaded media on S3-compatible object storage rather than the local disk, and who set credentials and an endpoint in config.properties.
  • Teams or communities that need federated groups, so a group hosted on one instance is reachable from accounts on other servers.
  • Contributors building from source with mvn package -DskipTests=true, who then place smithereen.jar and target/lib under /opt/smithereen and install libvips and imgproxy themselves.
  • Instance owners who maintain the two system services, smithereen and smithereen_imgproxy, through routine restarts and updates.

Getting started

The README recommends the installation script: install JDK 21 or newer and MySQL, download the prebuilt bundle for your CPU architecture from the latest release, unpack it, and run ./install.sh, answering a few questions to configure the server and create the first account. From there you point nginx or Caddy at Smithereen and imgproxy using the example configs, then finish settings in the admin UI.

How it compares

No list of paid products that Smithereen replaces is provided in these facts, and no competing self-hosted tools are named either, so within this registry it stands alone in its category rather than being positioned against alternatives. The comparison that the facts do support is internal: Smithereen is Unlicense-licensed and self-hosted, so there is no subscription to cancel and the operator keeps the database, the media, and the friend graph on their own infrastructure.

When to use it — and when not to

A self-hoster must operate MySQL, run libvips and imgproxy alongside the Java service, configure a reverse proxy, and keep two system services running through updates; the README explicitly warns that MariaDB, which several distributions install in place of MySQL, is known to be incompatible, so the database choice needs care. Anyone unwilling to maintain that stack, or expecting a managed hosting option, should not pick it. The project has 44 open issues and the README is installation-focused rather than a full operator manual, so expect to read the example configuration files and the release bundles closely when deploying.

project readme (upstream, from github) — read inline

Federated, ActivityPub-compatible social network with friends, walls, and groups.

If you have any questions or feedback, there's a Telegram chat you can join.

Crowdin

Building/installation

Running directly on your server

Recommended: use the installation script
  1. Install JRE or JDK 21 or newer from your distribution's package manager, here, here or here
  2. Install MySQL. Note: on Debian, apt-get install mysql-server would instead install MariaDB, which is known to be incompatible with Smithereen.
  3. Download a prebuilt bundle for your CPU architecture from the latest release to your server and unpack it somewhere
  4. Run ./install.sh
  5. Answer a few questions to configure Smithereen and create the first account. If you're using S3 storage for files, see the section about that below to better understand what the script asks you and configure your storage provider correctly.
  6. Configure your web server to proxy the requests to Smithereen and imgproxy and serve user-uploaded files. See example configs for nginx and Caddy.
  7. Log into your admin account from your web browser, then configure the rest of the server settings from its UI
Updating from an older version

Download the release bundle for the new version, unpack it, and run ./update.sh. Pass your installation directory as an argument to this script if it's not /opt/smithereen.

Alternatively, do the same thing manually

Stop services:

service smithereen stop
service smithereen_imgproxy stop

Copy smithereen.jar, imgproxy, libvips libraries and their symlinks, and the lib directory over your existing installation. Important: make sure that you do not merge the contents of the lib directories from your old and new installations, or the JVM class loader will get angry.

Start the services back up:

service smithereen start
service smithereen_imgproxy start

The first startup after installing an update might take a while as the new Smithereen version performs database migrations.

Install manually from sources
  1. Install JDK 21 or newer from your distribution's package manager, here, here or here
  2. Install MySQL. Note: on Debian, apt-get install mysql-server would instead install MariaDB, which is known to be incompatible with Smithereen.
  3. Build the jar by running mvn package -DskipTests=true, place it at /opt/smithereen/smithereen.jar and also copy the dependencies from target/lib. You should end up with this file structure:
    /opt/smithereen
├╴ smithereen.jar
└╴ lib
   ├╴ activation-1.1.jar
   └╴ ...other dependencies
  4. Somehow cause libvips to exist on your system: use the one from a release bundle, download a prebuilt one from here, or build it from sources, maybe using the CI build script. If you already have libvips installed on your system, you may skip this step, but be aware that not all libvips builds include all the features Smithereen needs.
  5. Install and configure imgproxy
  6. Fill in the config file, see a commented example here
    • You can use either the local file system (default) or an S3-compatible object storage service for user-uploaded media files.
  7. Create a new MySQL database and initialize it with the schema using a command (mysql -p smithereen .amazonaws.com by default. Required if not using AWS.
  • upload.s3.key_id and upload.s3.secret_key: your credentials for request authentication.
  • upload.s3.bucket: the name of your bucket.
  • upload.s3.override_path_style: if upload.s3.endpoint is set, set this to true if your cloud provider requires putting the bucket name into the hostname instead of in the path for API requests, like ..
  • upload.s3.protocol: https by default, can be set to http.

The following properties control the public URLs for clients to read the files from your S3 bucket. These are used for imgproxy and given out to clients directly when they click "Open original" in the image viewer, and will be used for non-image (e.g. video) attachments in a future Smithereen version:

  • upload.s3.hostname: defaults to s3-.amazonaws.com. Needs to be set if not using AWS and upload.s3.alias_host is not set.
  • upload.s3.alias_host: can be used instead of upload.s3.hostname if you don't want your bucket name to be visible. Requires that you have a CDN or a reverse proxy in front of the storage provider.
    • If this is set, the bucket name is not included in the generated URLs. The URLs will have the form of :///.
    • If this is not set, the generated URLs will be of the form :////.

You will need to configure your bucket to allow anonymous read access to objects, but not allow directory listing. Refer to Mastodon documentation on how to do this on different cloud providers.

You will also need to configure imgproxy to allow it to access your S3 storage:

IMGPROXY_ALLOWED_SOURCES=local://,https://<your S3 hostname or alias host>/

Make sure to include a trailing slash in the URL.

Contributing

If you would like to help translate Smithereen into your language, please do so on Crowdin. If your language isn't listed there, please ask to have it added.

If you would like to add a feature, please ask first before starting to work on it! This project is mostly "open-source but not open-contribution" because I (@grishka) have a rather specific vision of what it should be — an old-school social network that one primarily uses to stay up to date on the lives of people they know IRL and get to know these people better. An important part of that vision is to limit people's exposure to out-of-network content (created by those they don't have any connections with) as much as possible. The intended way to explore the network is by going along the social graph or (coming in the future) search for people. In particular, the following features will definitely not be added:

  • Hashtags. The whole idea behind them is to be able to easily see what people you don't know post about some topics or global events. They thus serve as an easy gateway to out-of-netw

readme truncated — read the full docs on github

Frequently asked questions

Is Smithereen free to use?

Smithereen is open source under the Unlicense licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does Smithereen do?

Federated, ActivityPub-compatible social network server with friends, walls, and groups.

What is Smithereen written in?

Smithereen is primarily written in Java. Its source is publicly available at https://github.com/grishka/Smithereen, and it has 546 GitHub stars.