Hacking a custom homepage for your Mastodon instance
Starting with version 4.0.0, Mastodon's homepage is not that great. It defaults to the "explore" page that basically shows the public timeline of that instance. If you want to know more you have to click on the "Learn more" button and then you're presented with the about page that shows the long description of the instance, the rules and the list of moderated servers. And it all shows up in a column centered on the page, which is kinda limiting.
You can add some html tags to the description of the instance. That is good. But you can't do it in the rules section, where you can't even add hyperlinks.
In our instance, Ciberlândia, we decided to hack a custom homepage:
Looks good, doesn't it? aiscarvalho and rlafuente did a great work with the design of the page.
We didn't want to mess with the Mastodon source code, so we did it all by hacking a few rules in the NGINX config.
First step: Create your homepage html
SSH to your server as the mastodon user (or sudo - mastodon if you're already logged in as root).
Create the directory where your html will be. We used /home/mastodon/live/custom-index/. Put your index.html, images and css files in there.
Second step: Add rules to NGINX config
In this step you have to be logged in as root.
Edit the file /etc/nginx/sites-available/mastodon and add these lines (don't forget to change you Content-Security-Policy according to your needs):
# START CUSTOM HOMEPAGE
location /welcome {
rewrite ^ /welcome/ redirect;
}
location /welcome/ {
alias /home/mastodon/live/custom-index/;
add_header Content-Security-Policy "default-src 'none'; font-src 'self'; img-src 'self' data:; script-src 'self'; style-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
add_header X-XSS-Protection "1; mode=block";
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains; preload';
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options nosniff;
}
location = / {
if ($cookie__session_id = "") {
rewrite ^/$ https://<**your instance url in here**>/welcome/ redirect;
}
try_files $uri @proxy;
}
# END CUSTOM HOMEPAGE
Final step: restart NGINX
Run this:
systemctl restart nginx
Now when a user tries to access the root of your site, NGINX will check if the user is logged in (checking the value of the cookie session_id) and redirect them to your custom page which is located at the /welcome/ path.
If the user is logged in, they will of course be served the default Mastodon interface.
[EDIT 2023-03-12] Added security headers
tags: mastodon, nginx, ciberlandia