2020-01-01 22:37:59 +01:00
---
title: Installing from source
2020-01-12 14:11:56 +01:00
description: Instructional guide on creating your own Mastodon-powered website.
2020-01-01 22:37:59 +01:00
menu:
docs:
weight: 20
parent: admin
---
2020-01-12 14:11:56 +01:00
## Pre-requisites {#pre-requisites}
2020-01-01 22:37:59 +01:00
2022-03-31 10:14:51 +02:00
* A machine running **Ubuntu 20.04** or **Debian 11** that you have root access to
2022-11-20 07:34:38 +01:00
* A **domain name** (or a subdomain) for the Mastodon server, e.g. `example.com`
2020-01-01 22:37:59 +01:00
* An e-mail delivery service or other **SMTP server**
2022-11-20 08:03:43 +01:00
You will be running the commands as root. If you aren’ t already root, switch to root: `sudo su -`
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
### System repositories {#system-repositories}
2020-01-01 22:37:59 +01:00
2022-03-31 10:14:51 +02:00
Make sure curl, wget, gnupg, apt-transport-https, lsb-release and ca-certificates is installed first:
```bash
apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates
```
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
#### Node.js {#node-js}
2020-01-01 22:37:59 +01:00
2021-03-04 04:16:02 +01:00
```bash
2022-03-31 10:14:51 +02:00
curl -sL https://deb.nodesource.com/setup_16.x | bash -
2020-01-01 22:37:59 +01:00
```
2022-03-31 10:14:51 +02:00
#### PostgreSQL {#postgresql}
2020-01-01 22:37:59 +01:00
2021-03-04 04:16:02 +01:00
```bash
2022-03-31 10:14:51 +02:00
wget -O /usr/share/keyrings/postgresql.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/postgresql.list
2020-01-01 22:37:59 +01:00
```
2021-03-04 04:16:02 +01:00
### System packages {#system-packages}
```bash
apt update
apt install -y \
imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \
g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \
bison build-essential libssl-dev libyaml-dev libreadline6-dev \
zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \
nginx redis-server redis-tools postgresql postgresql-contrib \
2022-03-31 10:14:51 +02:00
certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev
```
#### Yarn {#yarn}
```bash
corepack enable
2022-11-20 07:45:15 +01:00
yarn set version classic
2021-03-04 04:16:02 +01:00
```
2020-01-12 14:11:56 +01:00
### Installing Ruby {#installing-ruby}
2020-01-01 22:37:59 +01:00
We will be using rbenv to manage Ruby versions, because it’ s easier to get the right versions and to update once a newer release comes out. rbenv must be installed for a single Linux user, therefore, first we must create the user Mastodon will be running as:
2021-03-04 04:16:02 +01:00
```bash
2020-01-01 22:37:59 +01:00
adduser --disabled-login mastodon
```
We can then switch to the user:
2021-03-04 04:16:02 +01:00
```bash
2020-01-07 02:30:05 +01:00
su - mastodon
```
2020-01-01 22:37:59 +01:00
And proceed to install rbenv and rbenv-build:
2021-03-04 04:16:02 +01:00
```bash
2020-01-01 22:37:59 +01:00
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv & & src/configure & & make -C src
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
```
Once this is done, we can install the correct Ruby version:
2021-03-04 04:16:02 +01:00
```bash
2023-11-23 17:25:29 +01:00
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.2.2
rbenv global 3.2.2
2020-01-01 22:37:59 +01:00
```
We’ ll also need to install bundler:
2021-03-04 04:16:02 +01:00
```bash
2020-01-01 22:37:59 +01:00
gem install bundler --no-document
```
Return to the root user:
2021-03-04 04:16:02 +01:00
```bash
2020-01-07 02:30:05 +01:00
exit
```
2020-01-12 14:11:56 +01:00
## Setup {#setup}
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
### Setting up PostgreSQL {#setting-up-postgresql}
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
#### Performance configuration (optional) {#performance-configuration-optional}
2020-01-01 22:37:59 +01:00
2023-10-04 09:43:14 +02:00
For optimal performance, you may use [pgTune ](https://pgtune.leopard.in.ua/#/ ) to generate an appropriate configuration and edit values in `/etc/postgresql/16/main/postgresql.conf` before restarting PostgreSQL with `systemctl restart postgresql`
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
#### Creating a user {#creating-a-user}
2020-01-01 22:37:59 +01:00
You will need to create a PostgreSQL user that Mastodon could use. It is easiest to go with “ident” authentication in a simple setup, i.e. the PostgreSQL user does not have a separate password and can be used by the Linux user with the same username.
Open the prompt:
2021-03-04 04:16:02 +01:00
```bash
2020-01-07 02:30:05 +01:00
sudo -u postgres psql
```
2020-01-01 22:37:59 +01:00
In the prompt, execute:
```sql
CREATE USER mastodon CREATEDB;
\q
```
Done!
2020-01-12 14:11:56 +01:00
### Setting up Mastodon {#setting-up-mastodon}
2020-01-01 22:37:59 +01:00
It is time to download the Mastodon code. Switch to the mastodon user:
2021-03-04 04:16:02 +01:00
```bash
2020-01-07 02:30:05 +01:00
su - mastodon
```
2020-01-12 14:11:56 +01:00
#### Checking out the code {#checking-out-the-code}
2020-01-01 22:37:59 +01:00
Use git to download the latest stable release of Mastodon:
2021-03-04 04:16:02 +01:00
```bash
2022-11-20 07:34:38 +01:00
git clone https://github.com/mastodon/mastodon.git live & & cd live
2023-10-10 14:52:08 +02:00
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
2020-01-01 22:37:59 +01:00
```
2020-01-12 14:11:56 +01:00
#### Installing the last dependencies {#installing-the-last-dependencies}
2020-01-01 22:37:59 +01:00
Now to install Ruby and JavaScript dependencies:
2021-03-04 04:16:02 +01:00
```bash
2020-04-21 22:09:55 +02:00
bundle config deployment 'true'
bundle config without 'development test'
2020-04-05 17:11:06 +02:00
bundle install -j$(getconf _NPROCESSORS_ONLN)
2020-01-01 22:37:59 +01:00
yarn install --pure-lockfile
```
2020-04-05 17:11:06 +02:00
{{< hint style = "info" > }}
The two `bundle config` commands are only needed the first time you're installing dependencies. If you're going to be updating or re-installing dependencies later, just `bundle install` will be enough.
{{< / hint > }}
2020-01-12 14:11:56 +01:00
#### Generating a configuration {#generating-a-configuration}
2020-01-01 22:37:59 +01:00
Run the interactive setup wizard:
2021-03-04 04:16:02 +01:00
```bash
2020-01-01 22:37:59 +01:00
RAILS_ENV=production bundle exec rake mastodon:setup
```
This will:
* Create a configuration file
* Run asset precompilation
* Create the database schema
2022-11-20 07:34:38 +01:00
The configuration file is saved as `.env.production` . You can review and edit it to your liking. Refer to the [documentation on configuration. ]({{< relref "config" >}} )
2020-01-01 22:37:59 +01:00
You’ re done with the mastodon user for now, so switch back to root:
2021-03-04 04:16:02 +01:00
```bash
2020-01-07 02:30:05 +01:00
exit
```
2023-10-05 09:51:39 +02:00
### Acquiring a SSL certificate {#acquiring-a-ssl-certificate}
We’ ll use Let’ s Encrypt to get a free SSL certificate:
```bash
certbot certonly --nginx -d example.com
```
This will obtain the certificate, and save it in the directory `/etc/letsencrypt/live/example.com/` .
2020-01-12 14:11:56 +01:00
### Setting up nginx {#setting-up-nginx}
2020-01-01 22:37:59 +01:00
Copy the configuration template for nginx from the Mastodon directory:
2021-03-04 04:16:02 +01:00
```bash
2020-01-01 22:37:59 +01:00
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
```
Then edit `/etc/nginx/sites-available/mastodon` to replace `example.com` with your own domain name, and make any other adjustments you might need.
2023-10-05 09:51:39 +02:00
Un-comment the lines starting with `ssl_certificate` and `ssl_certificate_key` , updating the path with the correct domain name.
2020-01-01 22:37:59 +01:00
2023-10-05 09:51:39 +02:00
Reload nginx for the changes to take effect:
2022-11-20 07:41:21 +01:00
```bash
systemctl reload nginx
```
2020-01-01 22:37:59 +01:00
At this point you should be able to visit your domain in the browser and see the elephant hitting the computer screen error page. This is because we haven’ t started the Mastodon process yet.
2020-01-12 14:11:56 +01:00
### Setting up systemd services {#setting-up-systemd-services}
2020-01-01 22:37:59 +01:00
Copy the systemd service templates from the Mastodon directory:
2021-01-16 14:58:17 +01:00
```sh
2020-01-01 22:37:59 +01:00
cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
```
2021-01-16 14:58:17 +01:00
If you deviated from the defaults at any point, check that the username and paths are correct:
2020-01-01 22:37:59 +01:00
2021-01-16 14:58:17 +01:00
```sh
$EDITOR /etc/systemd/system/mastodon-*.service
```
2020-01-01 22:37:59 +01:00
Finally, start and enable the new systemd services:
2021-01-16 14:58:17 +01:00
```sh
2020-01-07 02:30:05 +01:00
systemctl daemon-reload
2021-01-16 14:58:17 +01:00
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
2020-01-01 22:37:59 +01:00
```
2021-01-16 14:58:17 +01:00
They will now automatically start at boot.
2020-01-01 22:37:59 +01:00
{{< hint style = "success" > }}
**Hurray! This is it. You can visit your domain in the browser now!**
{{< / hint > }}