💾 Archived View for tris.fyi › projects › amethyst › quickstart.gmi captured on 2023-09-28 at 15:40:51. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-01-08)
-=-=-=-=-=-=-
This page describes how to install Amethyst configured for a static site with automatic TLS certificate management.
You will need a working Python 3 installation (only 3.9 has been tested) with the pip package manager (or with the venv module if you intend to install in a virtual environment). On Debian, you can run the following to install dependencies:
$ sudo apt install python3 python3-pip python3-venv
First, download Amethyst.
$ git clone https://github.com/an-empty-string/amethyst.git $ cd amethyst
Amethyst is a Python package. You can install it in your system Python environment, your user Python package path, or in a Python virtual environment. Choose the applicable option from the following.
Install to the system Python package path; the Amethyst executable will be installed in "/usr/local/bin/amethyst":
$ sudo pip install .
Install to your user Python package path; the Amethyst executable will be installed in "~/.local/bin/amethyst":
$ pip install --user .
Create a virtual environment and install Amethyst there; the Amethyst executable will be installed in "~/amethyst-env/bin/amethyst":
$ python3 -m venv ~/amethyst-env $ source ~/amethyst-env/bin/activate $ pip install .
Next, you will need to write a configuration file. Amethyst configuration is written in JSON. Here is a minimal configuration that automatically manages certificates and serves files out of "/var/gemini" when receiving requests directed at "localhost". CGI and directory listing are turned on:
{
"hosts": {
"localhost": {
"paths": {
"/": {
"root": "/var/gemini",
"autoindex": true,
"cgi": true
}
}
}
}
}
Adjust the configuration appropriately, save the configuration to a file ("amethyst.conf" is a good choice), and put some ".gmi" files in the directory you've specified. Run Amethyst with your config like this:
$ /path/to/amethyst amethyst.conf
"/path/to/amethyst" is the path to the Amethyst executable as described in the section above.
If you've kept directory listings enabled, Amethyst will produce a directory listing whenever you try to navigate to a folder, unless there is an "index.gmi" in that folder (in which case that will be served instead).
If you've disabled directory listings, you'll just get a 51 Not Found when browsing to a folder without an "index.gmi".
If you've kept CGI enabled, any files marked executable (chmod +x) will be executed as CGI. There are a few other CGI quirks:
Certificates will be placed in the current directory. You almost certainly don't want this; you can set the "STATE_DIRECTORY" environment variable to change where these files are stored.
If you want Amethyst to start when your system starts, make a systemd unit file to do so. Here is an example systemd unit file with recommended options, assuming you installed Amethyst to the system Python package path and put your configuration in "/etc/amethyst.conf". Save it as "/etc/systemd/system/amethyst.service":
[Unit] Description=Amethyst Gemini server [Service] ExecStart=/usr/local/bin/amethyst /etc/amethyst.conf DynamicUser=yes ReadWritePaths=/var/gemini StateDirectory=amethyst [Install] WantedBy=multi-user.target
Start and enable the unit file with "sudo systemd enable --now amethyst.service". Amethyst will now run under its own user account and store certificates in "/var/lib/amethyst" as specified by the StateDirectory parameter.
You can reload configuration without restarting the server by sending SIGHUP to the Amethyst process.