capsule.town: Getting started

Return home

🚀 We're excited for you to join capsule.town!

🚧 Please note that this service is currently in early beta. Please get in touch if you have any feedback, bug reports, or would like to contribute.

Intro

Publishing your capsule is handled through a HTTP API, however we recommend most people make use of our official wrapper client, which is described below.

🗒 Note: whilst we encourage use of the Gemini protocol for publishing and consuming text content, we do use HTTPS for our management API. The HTTP/S protocol offers the useful tooling required for such management, and it's more about using the right tool for the job 🙂

Getting started guide

1. Download the client

We recommend most people download and make use of the capsule.town client, called `captown`, for publishing their capsule. However, if you'd rather use your own tooling (cURL, or something else) you can interface directly with the service using HTTPS (documentation for this is coming soon).

The current version of the client is: 0.1. Replace the version numbers in commands below to get the latest version.

You can use CURL to get the client, as described below.

For Linux:

For Mac:

ℹ️ We do not yet have a Windows version, but contributions are welcome.

Once downloaded:

1. Mark the binary as executable: `chmod +x captown`

2. Move the binary to a location of your choosing: e.g. `sudo mv captown /usr/local/bin`.

The rest of this guide assumes the binary is somewhere on your `PATH` and can be invoked using `captown` (as above).

🗒 Note: the source code of the binary can be examined. Please find a link to the source from the project homepage.

2. Prepare your capsule

You can now create a new capsule. To do so, create a new project directory (e.g. `~/projects/my_capsule`) and change into it:

Now create a `capsule/` directory inside this project - this is where your Gemini files will be stored. The client looks for a `capsule/` directory when publishing your capsule:

Create a new file called `capsule/index.gmi` and write a welcome message inside:

3. Create your capsule

By creating and publishing your capsule on capsule.town, you agree to the capsule.town rules.

Check out the rules

The next step is to create your new capsule on capsule.town. To do so, run:

The client will ask for a few details:

Name: the name of your capsule. This will be used as the subdomain, and will host your capsule at `<name>.capsule.town`. It must only contain letters and numbers and it must be unique.

Contact details: _this is optional_. If you like, you can leave an email, Telegram handle, or another contact identifier. We only use this when verifying ownership in case you lose your access credentials.

Once done, your capsule will be created and the access key will be written to `~/.capsules.yaml`.

⚠️ **IMPORTANT: Please remember to backup this file (e.g. to your password manager). If you lose your access keys you will not be able to publish any new updates.**

4. Publish your capsule

Finally, you can publish your capsule.

Run `captown publish` inside your project directory. The program will ask for your capsule name to create the deployment.

Alternatively you can run the following to publish your capsule non-interactively:

Whichever route you choose, if all goes well you'll then be able to visit `gemini://<name>.capsule.town` using your Gemini client to view your new capsule.

🗒 Note: the `publish` command must be run from the root of your project (i.e. the directory containing the `capsule/` sub-directory).

5. View your capsule's logs

You can see an access log of your capsule by running the `logs` command:

View other options for this command by running `captown help logs`.

Making updates

When you've made updates that you want to publish, simply run `captown publish` again to make them live.

Side note: we recommend committing your capsule project directory to source control as you would for any other project.

Return home