Agate - A simple gemini server

DidierMalenfant

Title: Agate on Cloudron - A simple gemini server

Main Page: https://github.com/mbrubeck/agate
Git: https://code.malenfant.net/didier/agate-app
Licence: MIT
Docker: didiermalenfant/net.malenfant.agate:20250709-011124-02250deeb
Demo: https://gemini.malenfant.net

Summary: Allows users to install a gemini server on cloudron in one-click.

Notes: I use Gemini for some different kind of content than I do on my regular blog. The crowd reading gemini 'capsules' (as they are known) is also very different from the main 'big' web. Kinda like Mastodon vs Twitter.
This is my first cloudron app. I welcome all comments and help with fixes for things I got wrong.

timconsidine

Upvoted
I like the cleanliness of project gemini and resulting sites (capsules).
Acknowledging that it is not meant as a replacement for HTTP(S) sites, there is clearly a community that it appeals to, and it would be good to service those and grow the community by having Agate on Cloudron.

LoudLemur

What is the procedure to try and install this on Cloudron?

LoudLemur

@DidierMalenfant

Well done on getting this going!
Since you like the Gemini Protocol, you might also be interested in the following requests:

DidierMalenfant

@LoudLemur said in Agate - A simple gemini server:

What is the procedure to try and install this on Cloudron?

Make sure your Cloudron backups are up to date
Clone the app's repo from https://code.malenfant.net/didier/agate-app.git
Install the cloudron CLI
Login to your cloudron server
CD into the cloned repo's folder
Type cloudron install --image:didiermalenfant/net.malenfant.agate:latest
Enter the subdomain you want to install the app at.

Let me know if you encounter any issues. This is pre-release software but it would be good to get feedback from other people too.

LoudLemur

@DidierMalenfant
Thanks. Though the gemini protocol aims to be simple, setting up a server is not easy!

Lets see how far we get:

Clone
On one's local machine, clone the agate repo on github by creating a folder, going into it and running:

git clone https://code.malenfant.net/didier/agate-app.git

Move Agate to your Cloudron
It helps to have a GUI, so install the Cubby application on Cloudron.
Then, open Cubby's file browser and use it to upload the agate folder to an appropriate place (where?!) on your Cloudron.

DidierMalenfant

@LoudLemur said in Agate - A simple gemini server:

Move Agate to your Cloudron
It helps to have a GUI, so install the Cubby application on Cloudron.
Then, open Cubby's file browser and use it to upload the agate folder to an appropriate place (where?!) on your Cloudron.

Wait... I'm confused. Where are those steps from? The next step in my list above was to install the cloudron CLI.

timconsidine

@LoudLemur Didier’s instructions were correct

in your cloudron instance
Make sure your Cloudron backups are up to date

on your local desktop / laptop :

open your terminal program
Clone the app's repo from https://code.malenfant.net/didier/agate-app.git
Install the cloudron CLI (this is one time task, do it once, then you can install any custom app)
npm install -g cloudron
Login to your cloudron server
cloudron login my.example.com
CD into the cloned repo's folder
Type cloudron install --image:didiermalenfant/net.malenfant.agate:latest
Enter the subdomain you want to install the app at, e.g. agate.domain.tld

in your cloudron instance :

find the app in in your cloudron portal - use as any other installed app
use the app’s File Manager to open public folder and create your index.gmi

GUI’s are helpful but you don’t need Cubby for this.
It’s only 3 terminal commands (plus the one-off command to install Cloudron CLI if you don’t have it already)
Be brave - you can do it

timconsidine

@LoudLemur are you on windows or Mac ? Or Linux ?

LoudLemur

Thank you both!
If you try this on Windows, you may well run into loads of problems with permissions in the powershell preventing you from running scripts, and a cascade of other issues I didn't note and log, anyway:
there is a problem when you try to install it:

cloudron install --image:didiermalenfant/net.malenfant.agate:latest
error: unknown option '--image:didiermalenfant/net.malenfant.agate:latest'

timconsidine

@LoudLemur another way to do it is to download the repo as a zip and unzip into a folder.
But if you have cloned successfully, that doesn’t offer much advantage.

After cloning or downloading the repo, you can build the image file yourself and use your version, not Didier’s.

But this requires you have to have docker installed on your windows box. And a docker registry.

Maybe Didier can advise about the image instruction.
I built my own image so don’t know if there’s an issue with the link he mentioned

timconsidine

@LoudLemur try ….

cloudron install —image didiermalenfant/net.malenfant.agate:latest
In other words put a space not a colon after ‘image’

I don’t know if his registry needs auth but as he suggested it, maybe not
That may be a docker hub so no auth needed

DidierMalenfant

@timconsidine said in Agate - A simple gemini server:

@LoudLemur try ….
cloudron install —image didiermalenfant/net.malenfant.agate:latest
In other words put a space not a colon after ‘image’

Yep, good catch. That's totally a typo on my part.

robi

May be useful to review last years effort for trying new apps:
https://forum.cloudron.io/topic/10966/installing-custom-apps-on-cloudron/

LoudLemur

This post is deleted!

LoudLemur

I think it would help if some additional notes were added in the "First Time Setup" section indicating into which folder to store one's gemlogs and how sub-folders might be used. Also, the example page is beautifully simple, but it could help if the index page linked to some additional gemlog pages, so it is already a landing site which shows you what other pages are available.

I think Agate supports multiple users, so that might end up with some confusion, too.

Here is a "killer feature" which might make gemlog hosting using Agate on Cloudron all the rage: analytics using goaccess. @girish, this feature might also be very much appreciated in several other cloudron applications too, e.g. Ghost, Grave, Wordpress, etc:

goaccess

This is a beautiful and simple way to see data. First, admire the beauty in the demo here:
https://rt.goaccess.io/?20250113204951

Here is the main site:
https://goaccess.io/

Here is what might work to help people running Agate see how many people visit their gemlog:

Primitive method - bash (how many visits to my gemlog)

wc -l access.log

via AI:

The Best-in-Class Visualizer: goaccess

For visualization, the undisputed champion in the text-based world is GoAccess. It’s a real-time log analyzer that runs directly in your terminal and can also generate a self-contained HTML report. It’s perfect for Gemini.

What it is: A single, fast C program with no dependencies.
How it works: You point it at your log file and tell it the log format. It instantly generates interactive terminal dashboards.

Why it’s great:
Real-time: You can see hits as they happen.
Terminal UI: It’s beautiful and navigable entirely with a keyboard.
HTML Reports: Can generate a clean, single-file HTML report you can view in a browser.
No Databases: It reads directly from the log file.
How to use it:
You need to tell goaccess your log format. For a server like Agate or , you might run it like this:

goaccess access.log --log-format='%d %t %h "%r" %s "%u"' --date-format='%Y-%m-%d' --time-format='%H:%M:%S'

(You will need to slightly adjust the --log-format string to perfectly match your server’s output, but this is a common starting point).
What it visualizes for you:

Total Requests and Unique Visitors (by IP).
A scrolling log of recent hits.
Top Requested Files (your most popular pages).
Static Requests (images, css if you were on the web).
Not Found (404) URLs.
Visitor Hostnames and IPs.
Operating Systems and Browsers (Gemini clients).
Time Distribution (hits per hour).

GoAccess Terminal UI
This is the best “native” tool for getting a rich, visual overview of your Gemlog’s traffic.

LoudLemur

From ai:

"The Key Concept: The Agate App Container

On Cloudron, your Agate server runs inside a dedicated, isolated container. This container has its own filesystem. To analyze its logs, you need to access that filesystem. Cloudron provides two essential tools for this:
File Manager: Lets you browse the app’s files and find the exact path to your logs.
Web Terminal: Gives you a command-line shell inside the Agate container.
Step 1: Find Your Log File and Log Format
Before you can use GoAccess, you need to know exactly where the log file is and what format it uses.
Go to your Cloudron dashboard and open the settings for your Agate app.
Open the File Manager.
The log file is typically stored in the app’s persistent data directory, /app/data/. Look for a file named access.log or similar. The most likely path is /app/data/access.log.
Click on the access.log file to view its contents. Take note of a single line. It will look something like this:
2023-10-27T15:45:01Z 172.18.0.1 "gemini://my.capsule.com/page.gmi" 20 "Lagrange"
From this line, we can determine the log format GoAccess will need. This format is:
%d %t %h "%r" %s "%u"
Now that we have the path and format, we can choose a method."

I used the file browser to look in app/data and couldn't see any logs there, so I don't know what the actual format looks like. If we knew it, that could help us setup goaccess.

One of the things about (low traffic) gemini sites is that it is difficult to know if anybody ever visits at all. It would be lovely to have some data.

LoudLemur

@girish I think it would be great if Cloudron had a presence in gemini-space. I have automated a 4 part gemlog which could be used as a starting point for how to get going self-hosting a gemlog on Agate by deploying with Cloudron:

Part 1: Introduction to Self-Hosting Your Gemini Capsule with Agate on Cloudron

# Self-Hosting Your Gemini Capsule: A Simple Guide (Part 1 of 4)

Welcome to this gemlog series! If you're tired of bloated web hosting and want a lightweight, privacy-focused alternative, Gemini is for you. In this 4-part guide, we'll walk through self-hosting your own Gemini server using Agate on Cloudron. We'll even add beautiful analytics with GoAccess.

## Why Gemini and Agate?
Gemini is a simple protocol for serving text-based content—think of it as a minimal web alternative. Agate is an easy-to-use Gemini server that's perfect for beginners.

* Low resource use: Runs on cheap VPS or even a Raspberry Pi.
* Easy deployment: Cloudron handles the heavy lifting.
* Analytics: Track visitors with GoAccess without invading privacy.

For the best viewing experience, apply the Solarized Dark theme in your Gemini browser (e.g., Lagrange). It uses a minimalist, eye-friendly palette:
- Background: #002b36 (deep blue-gray)
- Text: #839496 (light gray)
- Links: #268bd2 (blue accent)
- Headings: #b58900 (yellow-orange)
- Preformatted: #073642 (darker blue-gray)

=> gemini://gemini.thegonz.net/gemlog/2021-03-20-lagrange-themes.gmi Guide to Theming in Lagrange

## What You'll Need
- A server or VPS (e.g., DigitalOcean, $5/month).
- A domain name.
- Basic command-line comfort.

In Part 2, we'll set up Cloudron and deploy Agate.

=> https://geminiprotocol.net/docs/faq.gmi Gemini Protocol FAQ
=> https://github.com/mbrubeck/agate Agate GitHub Repository
=> https://goaccess.io/ GoAccess Analytics Tool
=> https://forum.cloudron.io/topic/14046/agate-a-simple-gemini-server/8 Cloudron Forum: Setting Up Agate
=> gemini://your-capsule/part2.gmi Next: Part 2 - Setting Up Cloudron and Deploying Agate

Part 2: Setting Up Cloudron and Deploying Agate

# Self-Hosting Your Gemini Capsule: A Simple Guide (Part 2 of 4)

## Navigation
=> gemini://your-capsule/part1.gmi Previous: Part 1 - Introduction
=> gemini://your-capsule/part3.gmi Next: Part 3 - Hosting Your Gemlog

Now that you're excited about Gemini, let's get your server running. We'll use Cloudron, a platform that makes self-hosting apps (like Agate) a breeze—no manual config files or security headaches.

## Step 1: Set Up Cloudron
1. Sign up for Cloudron (free for basic use, paid for more features).
2. Install Cloudron on your server:
   - SSH into your VPS.
   - Run the installer script:
curl -sSL https://cloudron.io/cloudron-setup | sudo bash

3. Follow the on-screen prompts to set up your domain and admin account.
4. Access the Cloudron dashboard at https://my.cloudron.io.

=> https://cloudron.io/ Cloudron Official Site (for full docs)

## Step 2: Deploy Agate
1. In the Cloudron dashboard, go to the App Store.
2. Search for "Agate" and install it.
3. Configure your domain (e.g., gemini.yourdomain.com).
4. Cloudron handles TLS certificates automatically—your Gemini capsule will be secure!

Agate is now running in a container. You can access it via a Gemini browser like Lagrange.

=> https://gmi.skyjake.fi/lagrange/ Download Lagrange (Gemini Browser)

In Part 3, we'll create and host your first gemlog.

=> gemini://your-capsule/part1.gmi Previous: Part 1 - Introduction
=> gemini://your-capsule/part3.gmi Next: Part 3 - Hosting Your Gemlog

Part 3: Hosting Your Gemlog with Agate on Cloudron

# Self-Hosting Your Gemini Capsule: A Simple Guide (Part 3 of 4)

## Navigation
=> gemini://your-capsule/part2.gmi Previous: Part 2 - Setting Up Cloudron and Deploying Agate
=> gemini://your-capsule/part4.gmi Next: Part 4 - Adding Analytics with GoAccess

With Agate deployed, it's time to host content! Agate serves files from a directory, making it easy to create a "capsule" (Gemini site) with gemlogs (like blogs).

## Step 1: Access Agate's Files
1. In Cloudron dashboard, open your Agate app settings.
2. Use the File Manager to browse /app/data/public/ (this is where Agate serves files from).

## Step 2: Create Your Gemlog
1. Upload or create .gmi files via File Manager.
2. Example: Create index.gmi with this content:
Welcome to My Capsule!
This is my first gemlog entry.

=> about.gmi About Me
3. For a blog series, organize in a folder like /gemlog/ and link them.

## Step 3: Test It
Open your Gemini browser (e.g., Lagrange) and visit gemini://yourdomain.com/. Your content should appear!

Pro Tip: Use the Solarized Dark theme for a polished look—headings in yellow-orange (#b58900) pop against the deep blue-gray background (#002b36).

In Part 4, we'll add analytics to see who's visiting.

=> https://forum.cloudron.io/topic/14046/agate-a-simple-gemini-server/8 Cloudron Forum: More Agate Tips
=> gemini://your-capsule/part2.gmi Previous: Part 2 - Setting Up Cloudron and Deploying Agate
=> gemini://your-capsule/part4.gmi Next: Part 4 - Adding Analytics with GoAccess

Part 4: Adding Beautiful Analytics with GoAccess

# Self-Hosting Your Gemini Capsule: A Simple Guide (Part 4 of 4)

## Navigation
=> gemini://your-capsule/part3.gmi Previous: Part 3 - Hosting Your Gemlog

You've got a running capsule—now let's track visitors with GoAccess. Since Agate runs in a Cloudron container, we'll work inside it for analytics.

## Key Concept: Agate's Container
Cloudron isolates apps. Use Web Terminal and File Manager to access logs at /app/data/access.log. Log format: %d %t %h "%r" %s "%u"

## Method 1: Quick Manual Check
Open Web Terminal and run:
awk '{print $3}' /app/data/access.log | sort | uniq -c | sort -nr | head -n 20
## Method 2: Interactive GoAccess
Install in Web Terminal:
apt-get update apt-get install -y goaccess
Run:
goaccess /app/data/access.log --log-format='%d %t %h "%r" %s "%u"' --date-format='%Y-%m-%d' --time-format='%H:%M:%S'

(Note: Reinstall after restarts.)

## Method 3: Automated HTML Report (Recommended)

DidierMalenfant

@LoudLemur said in Agate - A simple gemini server:

I think Agate supports multiple users, so that might end up with some confusion, too.

The way the app is setup in my case is just to serve files located in /app/data/public. You can see the default index.gmi in there after you install; the app. Editing this and setting up the folder structure is left to the user as it's basically gemini stuff and not specific to the app itself.

I'm going to update the README in the repo to mirror @timconsidine's great step by step instructions on installing the image.

timconsidine

@DidierMalenfant a thought, just a thought, you know more about this

I saw Kineto : https://git.sr.ht/~sircmpwn/kineto
If I understand it correctly, it proxies gemini:// to http://
It's only 3 .go files (plus licence and readme)

If it were built into your agate deployment, would that deliver an app which effectively serves both gemini and http ?
That would be boost to some wanting to use gemini but not have their site only accessible in Lagrange etc.
Avoids an external proxy dependency like Smolnet

I think Cloudron base image supports go.

Tell me to shut up if I am barking up the wrong tree
<woof> <woof>

Cloudron makes it easy to run web apps like WordPress, Nextcloud, GitLab on your server. Find out more or install now.

Cloudron Forum

Agate - A simple gemini server

The Best-in-Class Visualizer: goaccess

The Best-in-Class Visualizer: goaccess