Documentation » Running your own server

Smithereen can run on just about any OS that can run a modern Java virtual machine, but this page assumes Linux. Recommended minimum system requirements for a server are:

  • 1 GB of RAM
  • 2 CPU cores
  • 10 GB of storage would be fine for a single-user server, but that depends on usage patterns a lot

A small-scale server (tens of users) can be easily run on a cheap VDS, a single-board computer like the Raspberry Pi, or even an old Android phone. The only hard requrements for a fediverse server are a public IP address and a domain. For anything that you intend to be used by hundreds of users or more, a dedicated server or an equivalent VDS configuration is recommended.

Running directly on your server

  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
  1. 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.
  2. Install and configure imgproxy
  3. 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.
  4. Create a new MySQL database and initialize it with the schema using a command (mysql -p smithereen < schema.sql) or any GUI like phpMyAdmin
  5. Configure and start the daemon: assuming your distribution uses systemd, copy the service file to /etc/systemd/system, then run systemctl daemon-reload and service smithereen start
  6. Run java -jar /opt/smithereen/smithereen.jar /etc/smithereen/config.properties init_admin to create the first account
  7. Configure your web server to proxy the requests to Smithereen and imgproxy and serve user-uploaded files. See example configs for nginx and Caddy.
  8. Log into that account from your web browser, then configure the rest of the server settings from its UI

Using Docker

Copy Docker-specific config example to the project root directory as config.properties and edit it to set your domain. Also edit docker-compose.yml to add your imgproxy secrets. You can then use docker-compose to run Smithereen, MySQL, and imgproxy. You still need to configure your web server: nginx, Caddy. Create the first account by running docker-compose exec web bash -c ./smithereen-init-admin.

Using S3 object storage

Smithereen supports S3-compatible object storage for user-uploaded media files (but not media file cache for files downloaded from other servers).

To enable S3 storage, set upload.backend=s3 in your config.properties. Configure other properties depending on your cloud provider:

  • upload.s3.region: the region to use, us-east-1 by default. Required for AWS, but some other cloud providers accept arbitrary values here.
  • upload.s3.endpoint: the S3 endpoint, s3.<region>.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 <bucket>.<endpoint>.
  • 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-<region>.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 <protocol>://<alias_host>/<object>.
    • If this is not set, the generated URLs will be of the form <protocol>://<hostname>/<bucket>/<object>.

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.