Installing glitch-soc from Source

Installing glitch-soc from Source.md

Installing glitch-soc from Source

glitch-soc is a feature-rich fork of Mastodon. Its installation process mirrors Mastodon's closely, with a few key differences when checking out the source code and deploying.

---

Pre-requisites

• A machine running Ubuntu 24.04 or Debian 13 with root access
• A domain name (or subdomain) for your server, e.g. example.com
• An email delivery service or other SMTP server

The examples below use example.com as the domain — replace it with your own before running any commands.

Run all commands as root. If you aren't already root, switch: sudo -i

---

System Repositories

Make sure curl, wget, gnupg, lsb-release, and ca-certificates are installed first:

apt install -y curl wget gnupg lsb-release ca-certificates

Node.js

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

PostgreSQL

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

---

System Packages

apt update
apt install -y \
  imagemagick ffmpeg libvips-tools libpq-dev libxslt1-dev file git \
  protobuf-compiler pkg-config autoconf bison build-essential \
  libssl-dev libyaml-dev libreadline-dev zlib1g-dev libffi-dev \
  libgdbm-dev nginx nodejs redis-server postgresql certbot \
  python3-certbot-nginx libidn-dev libicu-dev libjemalloc-dev

Yarn

Enable corepack so that the correct version of Yarn is installed automatically:

corepack enable

---

Creating the mastodon User

adduser --disabled-password mastodon

---

Setting up PostgreSQL

Performance Configuration (optional)

For optimal performance, use pgTune to generate an appropriate configuration:

• Select the appropriate PG version and OS Type
• Select Web application for DB Type
• Fill in your server's specs for the remaining values

Apply the generated values to /etc/postgresql/18/main/postgresql.conf, then restart:

systemctl restart postgresql

Creating a Database User

sudo -u postgres psql

In the prompt:

CREATE USER mastodon CREATEDB;
\q

---

Setting up glitch-soc

Switch to the mastodon user:

su - mastodon

Checking out the Code

Unlike mainline Mastodon, glitch-soc tracks the main branch of its own repository rather than tagged releases. Clone the glitch-soc repository:

git clone https://github.com/glitch-soc/mastodon.git live && cd live
git checkout main

Installing Ruby

Use rbenv to manage Ruby versions:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Then install the correct Ruby version:

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install

Installing Dependencies

bundle config deployment 'true'
bundle config without 'development test'
bundle install
yarn install

Note: The two bundle config commands are only needed on first install. For future updates, bundle install alone is sufficient.

Note: Because glitch-soc ships with two front-end flavours, asset precompilation requires more time and resources than it does on mainline Mastodon. Plan accordingly.

Generating a Configuration

Run the interactive setup wizard:

RAILS_ENV=production bin/rails mastodon:setup

This will:

• Create a configuration file (.env.production)
• Run asset precompilation
• Create the database schema

Review and edit .env.production as needed before proceeding.

Switch back to root when done:

exit

---

Acquiring an SSL Certificate

certbot certonly --nginx -d example.com

The certificate will be saved to /etc/letsencrypt/live/example.com/.

---

Setting up nginx

cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
rm /etc/nginx/sites-enabled/default

Edit /etc/nginx/sites-available/mastodon to:

1. Replace example.com with your domain
2. Uncomment the SSL certificate lines:

ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

3. Make any other adjustments needed.

Allow nginx's www-data user to access asset files:

chmod o+x /home/mastodon

Restart nginx:

systemctl restart nginx

At this point, visiting your domain should show the Mastodon error page — this is expected, as the Mastodon/glitch-soc processes haven't started yet.

---

Setting up systemd Services

cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/

Verify the username and paths are correct:

$EDITOR /etc/systemd/system/mastodon-*.service

Start and enable the services:

systemctl daemon-reload
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

The services will now start automatically on boot. Visit your domain in the browser — your glitch-soc instance should be live.

---

Updating glitch-soc

Since glitch-soc tracks main rather than tagged releases, updates are pulled directly from the repository. Run the following steps as the mastodon user from the ~/live directory:

1. Pull the latest source:

   git pull

2. Install dependencies:

   bundle install && yarn install

3. Run pre-deployment database migrations:

   RAILS_ENV=production SKIP_POST_DEPLOYMENT_MIGRATIONS=true bundle exec rails db:migrate

4. Pre-compile static assets:

   RAILS_ENV=production bundle exec rails assets:precompile

5. Restart services (run as root):

   systemctl reload mastodon-web && systemctl restart mastodon-{sidekiq,streaming}

6. Clear the Rails cache:

   RAILS_ENV=production bin/tootctl cache clear

7. Run post-deployment database migrations:

   RAILS_ENV=production bundle exec rails db:migrate

Migrating from Mastodon to glitch-soc

If you're switching an existing Mastodon instance to glitch-soc, add the glitch-soc remote and switch branches before following the update steps above:

git remote add glitch-soc https://github.com/glitch-soc/mastodon
git fetch glitch-soc
git checkout glitch-soc/main

Then proceed from step 2 of the update process.