Installing Ditto

This guide will teach you how to install Ditto on a Linux VPS (we recommend Ubuntu) using deno, systemd, and nginx.

1. System setup

1.a. Install updates

Usually a fresh VPS already has outdated software, so run the following commands to update it:

Ubuntu

sudo apt update
sudo apt upgrade

Fedora

sudo dnf check-update
sudo dnf update

Arch

sudo pacman -Syu

When prompted ([Y/n]) type Y and hit Enter.

1.b. Install system dependencies

Ditto relies on some additional system software in order to function. Install them with the following command:

Ubuntu

sudo apt install git curl unzip nginx postgresql-contrib certbot python3-certbot-nginx

Fedora

sudo rpm install git curl unzip nginx postgresql-contrib certbot python3-certbot-nginx

Arch

sudo pacman -S git curl unzip nginx postgresql-contrib certbot certbot-nginx

1.c. Install Deno

To install Deno system-wide, run:

curl -fsSL https://deno.land/x/install/install.sh | sudo DENO_INSTALL=/usr/local sh -s v2.0.0

TIP

For best compatibility, please stick to the version of Deno we recommend, which can be found in the release notes or the .tool-versions file.

1.d. Create the Ditto user

For security reasons, it’s best to run Ditto as a separate user with limited access.

We’ll create this user and call it ditto:

sudo adduser ditto

2. Install Ditto

It’s time to install Ditto. Let’s get things up and running.

2.a. Download source code

git clone https://gitlab.com/soapbox-pub/ditto /opt/ditto
chown -R ditto:ditto /opt/ditto

Enter the source code directory, and become the ditto user:

cd /opt/ditto
sudo su ditto

2.b. Configure Ditto

Run the following command to create a .env file:

deno task setup

Follow the instructions in the terminal to set up your .env file. Make note of the Postgres password you enter here. We will use it later.

TIP

If you choose to use the local uploader for more control over uploaded files, you'll have to set up an additional nginx rule. See "Configure nginx" below.

2.c. Add Soapbox

Ditto can serve any frontend (or none at all), but we recommend using Soapbox for the best experience.

Run this command to install Soapbox:

deno task soapbox

TIP

You can re-run this command at any time to update Soapbox to the latest version.

2.d. Provision the database

If you are still the ditto user, exit the shell:

exit

Create a new Postgres user and database for Ditto:

sudo -u postgres createuser -P ditto
sudo -u postgres createdb ditto -O ditto

Next up, set the password for the newly created ditto Postgres user.

sudo -u ditto psql # launch the Postgres cli client
ALTER USER ditto PASSWORD '<your-database-password-here>'; # Type this at the Postgres prompt
\q # Quit the Postgres client

Make sure the password you enter matches the one you entered into the setup script earlier.

2.e. Start Ditto

Copy the systemd unit file to the correct location:

sudo cp /opt/ditto/installation/ditto.service /etc/systemd/system/ditto.service

Reload the systemd manager configuration:

sudo systemctl daemon-reload

Enable the Ditto service to start automatically at boot and start it immediately:

sudo systemctl enable --now ditto

Now Ditto is running. You're almost done!

3. Getting online

The last step is to make your server accessible to the outside world. We’ll achieve that by installing Nginx and enabling HTTPS support.

3.a. Configure Nginx

Copy the Nginx configuration file to the correct location:

sudo cp /opt/ditto/installation/ditto.conf /etc/nginx/sites-enabled/ditto.conf

Next edit the configuration file to replace example.com with your domain name:

sudo nano /etc/nginx/sites-enabled/ditto.conf

3.b.i. Setting up nginx to serve local uploads

If you chose "Local" as the uploader above, you need to set up nginx to serve local uploads from the directory you selected.

server {
    server_name media.your.domain;

    location / {
        root </path/to/serve/local/files/from>;
        autoindex off;  # Optional: allows directory listing. We recommend keeping this off.
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
    location = /404.html {
        internal;
    }
}

3.b. Obtain an SSL certificate

Run the following command to obtain an SSL certificate from Let’s Encrypt:

sudo certbot --nginx

Follow the prompts to obtain the certificate.

3.c. Restart Nginx

Restart Nginx to apply the changes:

sudo systemctl restart nginx

🎉 Congrats, you’re done! Check your site in a browser and it should be online.

4. Sync your existing data

If you are already a Nostr user, you need to copy your existing profile data to Ditto before you use Ditto, or it could overwrite your profile. You can also get your friends' data and posts onto your Ditto instance. The more the merrier!

On the server that is running ditto, run the following command:

deno task nostr:pull <pubkey1> [pubkeys]... <relay1> [relays]...

The pubkeys can either be NIP-19 entities (i.e. npub1...) or hex-encoded strings (something like 0574536d3ef4d65faf95b42393610b8475d22f4c294649d46c50d5d36f75267c).

If you don't want to import posts and only get profiles, you can run:

deno task nostr:pull --profiles-only <pubkey1> [pubkeys]... <relay1> [relays]...

5. Post-installation

Below are some additional steps you can take after you’ve finished installation.

Promote a user to admin

To promote a user to admin, cd into the Ditto directory and run the following command:

deno task admin:role <pubkey> admin

Add relays

To get data into your server, you need to add relays. Ditto will store all data streamed from these relays.

In Soapbox, navigate to "Dashboard" > "Relays" and add the relays you want to ingest events from. Restart the Ditto server (systemctl restart ditto) for the changes to take effect.

WARNING

Keep the relay list small to avoid performance issues. We suggest using 1-3 relays.
Please see Known Issues for more information.

Update Ditto

To update Ditto, pull the latest changes from the repository and restart the service:

cd /opt/ditto
su ditto
git pull origin main
exit
sudo systemctl restart ditto

Renew SSL certificate

To renew the SSL certificate, run:

sudo certbot renew

Useful commands

Check Useful Commands for additional options.

Troubleshooting

Something not working right? First try Troubleshooting Ditto. If you can’t find a solution there, please open an issue and we’ll help you out.