My first attempt at a blog site involved trying to self-host a Wordpress site. For my purposes, this was massive overkill. I didn’t need the plug-ins, style customization, and general complexity. I just wanted a simple blog. So, Hugo was a great fit for my needs. If you want a good tutorial on how to set up workflow from Obsidian to Hugo, check out Network Chuck’s instructions on his blog .

After setting up my site, I wanted to add comments. This was pretty much the only Wordpress feature I wanted to include. To start, I hit up the Hugo documentation to find out what my options were. Hugo has native support for Disqus, but with that being a paid service I kept reading (I’m cheap). Heading to the open source section of the page, I hit pay dirt with the second link, Comentario . The documentation looked pretty good and it seemed like it would be happy living in a Docker container.

Setting it up in a Container#

The documentation has a good example of what the Docker compose file should look like. The one thing they were missing was a volume definition for the Postgres database. Without this, any data (configuration, users, comments, etc.) would be lost if the container were deleted. The page describes this as a “Docker Playground” so I’m guessing they meant it as just a demo site. However, all you need to do is to add a volume to the db service and now your data is persisted to disk on the host machine. Here’s the docker-compose.yml file:

services:
  comentario-db:
    image: postgres:17-alpine
    container_name: comentario-db
    environment:
      POSTGRES_DB: comentario
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./db:/var/lib/postgresql/data
    restart: always

  comentario:
    image: registry.gitlab.com/comentario/comentario
    container_name: comentario
    ports:
      - "8080:80"
    environment:
      BASE_URL: https://comments.yourdomain.com/
      SECRETS_FILE: "/secrets.yaml"
    volumes:
      - ./secrets.yaml:/secrets.yaml:ro
    restart: always
    depends_on:
	  - comentario-db

When this runs, a db folder will be created in the same folder as the docker-compose.yml file. Postgres will write its database files here, meaning it will survive recreating the Docker container and makes it easy to backup.

You’ll also need a .env file to supply the Postgres password for the database service:

POSTGRES_PASSWORD=<YOUR_PASSWORD_HERE>

The last file is the secrets.yaml file. Comentario will use this to access the database. If you add any oAuth providers like Google or Github for user authentication, the configuration information for those will end up here too.

postgres:
  host:     comentario-db
  port:     5432
  database: comentario
  username: postgres
  password: SAME_PASSWORD_AS_.env_FILE

Fire It Up#

That’s pretty much all you need to run the service. Use the dockcer compose command to bring up the containers.

docker compose up -d

The service should now be up and running.

Configure your Reverse Proxy#

If you’re self-hosting your blog, you probably have a reverse proxy (Traefik, Caddy, nginx Proxy Manager, etc.) and know how to add an entry to access the Comentario site. Just point it at the Docker host machine’s 8080 port. I use Caddy for my reverse proxy and I’ll create a followup post on how I set that up.

Set up the Super User#

Access the site via the URL you set up in your reverse proxy. Sign up as a user and configure your domain. Note that the first user to sign up becomes the super user with rights to everything, so set this up as soon as you can since anyone can do this if you stumble across your site.

Using Comentario with Hugo#

The Comentario site has some documentation on how to hook it up to Hugo, but it’s very basic and doesn’t really work well if you have a theme applied. Here’s what I did.

Create a Partial for Comments#

  1. Create the layouts/partials folder.
  2. Create a comments.html file.
{{ if .Site.Params.enableComments }}
<script defer src="{{ .Site.Params.comentarioURL }}"></script>
<comentario-comments></comentario-comments>
{{ end }}
  1. Find the [params] section of your site’s .toml file. replace comments.yourdomain.com with whatever you set up in your reverse proxy for the Cometario service.
  enableComments = true
  comentarioURL = "https://comments.yourdomain.com/comentario.js"
  1. I use the Terminal theme which is already set up to look for a comments.html partial when rendering the site’s HTML. See the bottom of this file .

If Your Theme Doesn’t Support Comments#

If the theme you’re using doesn’t account for having a comments partial, you’ll need to override its rendereing layout. See this documentation to help figure out which theme layout you’re using. It will likely be layouts/_default/single.html or layouts/post/single.html. Once you figure out which one you’re using, make your own version (same folder path) in your project and copy the code from the theme’s GitHub repo. Add the partial to the end. Yes, this isn’t a great solution since any updates to the theme won’t be applied automatically to your site now, but it’s the only way to really do it. If it really bothers you, pick a theme like Terminal that already has a way to add the comments partial.

{{ partial "comments.html" . }}

Conclusion#

That should do it. You’ll now be able to receive comments on your blog site. The Comentario app is quite feature filled an should provide you with lots of good info about the usage of your site in addition to allowing you to see user comments.