how to install ghost with isso comments on debian and nginx

so, here's one of those "how to install ghost with isso comments on debian buster and nginx" posts that can be indexed on the internet forever and likely go out of date in 6 months. so goes these guides, as i (tried, and failed) to follow one.

the ghost install guide for ubuntu gets us about 75% of the way there. it has steps for adding ssl as well, which you more or less need nowadays.

so, provided ghost is running, we can get down to adding isso.

apt install isso

isso configs work a lot like nginx, with an available and an enabled directory for configurations in /etc/isso.d. so create one in available and name it after your domain, and symlink it to enabled. the only real config you need to edit is the host line which will contain the URL of your ghost instance. enabling the admin interface at the bottom is recommended. enable and start the service.

this is where the documentation and other guides get the directions wrong, and here is how to correctly set the block in your nginx config. we don't even use a subdomain for isso, we just latch this right on under the location block that ghost uses in it's config.

    location /isso {
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Script-Name /isso;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:8000;
    }

to test your isso instance, reload nginx and hit the following endpoint in your browser: https://$GHOST_DOMAIN/isso/$GHOST_DOMAIN/admin and you'll get to your admin panel. the password will be what you set in the config file.

isso is designed so that one instance can handle a multitude of domains, so its endpoint is set up to handle that. this is not well explained in documentation.

on the ghost side of things, you have to edit the post.hbs file in your theme and add a section for the comments, also inject isso's javascript into the page.

<script data-isso="/isso/$GHOST_DOMAIN/" src="/isso/$GHOST_DOMAIN/js/embed.min.js"></script>
<section id="isso-thread"></section>

add a couple of <br />'s above it to space the comments out below your post, for good measure.

i don't have a good way of turning off commenting per-post. probably not doable. here's hoping the bots don't go wild in the moderation queue either. is blog spam actually still a thing in 2020?

boss rush