1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
#+title: Launching a Gemini Capsule
#+date: 2021-03-28
#+description: A guide to self-hosting a Gemini capsule on your own server.
#+filetags: :dev:
* What is Gemini?
[[https://gemini.circumlunar.space/][Gemini]] is an internet protocol
introduced in June 2019 as an alternative to HTTP(S) or Gopher. In
layman's terms, it's an alternative way to browse sites (called
capsules) that requires a special browser. Since Gemini is not
standardized as an internet standard, normal web browsers won't be able
to load a Gemini capsule. Instead, you'll need to use
[[https://gemini.%20circumlunar.space/clients.html][a Gemini-specific
browser]].
The content found within a Gemini page is called
[[https://gemini.circumlunar.space/docs/cheatsheet.gmi][Gemtext]] and is
/extremely/ basic (on purpose). Gemini only processes the text, no media
content like images. However, you're able to style 3 levels of headings,
regular text, links (which will display on their own line), quotes, and
an unordered list.
Here's a complete listing of valid Gemtext:
#+begin_src txt
# Heading 1
## Heading 2
### Heading 3
Regular text! Lorem ipsum dolor sit amet.
=> https://example.com My Website
=> gemini://example.com My Gemini Capsule
> "If life were predictable it would cease to be life, and be without flavor." - Eleanor Roosevelt
My List:
,** Item
,** Item
```Anything between three backticks will be rendered as code.```
#+end_src
*** Free Option
There are probably numerous websites that allow you to create your
personal Gemini capsule, but I'm going to focus on the two sites that I
have personally tested. The first option below, Midnight Pub, allows you
to create/edit any Gemini files you want in your account. This is
essentially a GUI option with a built-in text box for editing. The
second option below, Sourcehut, allows you to use a Git repository and
automatic build process to deploy your personal Gemini capsule every
time you push a commit.
** Midnight Pub - Beginner Friendly
[[https://midnight.pub/][Midnight Pub]] is a small, virtual community
meant to reflect the atmosphere of wandering into a small alley pub. The
site is built in Gemtext and has a server-side process to convert
Gemtext to HTML if someone loads the site in an HTTP(S) browser.
To create an account, you'll need to email the owner of the website to
obtain a key. You can find their email on the Midnight Pub homepage.
Once registered, head to [[https://midnight.pub/account][your account]]
and select [[https://midnight.pub/site][manage site]]. This is the
screen where you can upload or create any files to be displayed on the
internet.
For example, I've created both an HTML file and a Gemini file. Remember
that Gemini is automatically converted to HTML on the Pub, so you don't
need an HTML version. For example, I created an HTML version to add in
some extra styling.
All you need to do is create a page like =index.gmi= and use your Gemini
browser to head over to your-username.midnight.pub to see the result.
That's all there is to it! Easy enough, right? Let's check out a more
advanced version in the next section.
* Paid Option
As of 2021, Sourcehut has decided to require users to have a paid
account in order to utilize their automated build system. For now, paid
accounts can be as low as $2/month.
** Sourcehut
[[https://sourcehut.org/][Sourcehut]] is a collection of software
development tools, but mostly surrounds their hosted Git repository
service. Simply put, it's a minimal and more private alternative to
services like GitHub.
This walkthrough is more advanced and involves things like Git, SSH, the
command line. If you don't think you know enough to do this, check out
my walkthrough on creating a Gemini capsule for the Midnight Pub
instead.
The first thing you'll need to do is create an SSH key pair, if you
don't already have one on your system. Once created, grab the contents
of =id_rsa.pub= and add it to your Sourcehut account settings - this
will allow you to push and pull code changes without using a
username/password.
#+begin_src sh
ssh keygen
#+end_src
Next up, let's create a repository with the proper name so that the
Sourcehut build system will know we want them to host a website for us.
Use the following format exactly:
#+begin_src sh
mkdir your-username.srht.site && cd your-username.srht.site
#+end_src
Now that we've created the repo, let's initialize Git and add the proper
remote URL.
#+begin_src sh
git init
#+end_src
#+begin_src sh
git remote add origin git@git.sr.ht:~your-username/your-username.srht.site
#+end_src
Now that our repository is set up and configured, we will need to create
at least two files:
- =index.gmi=
- =.build.yml=
For your =.build.yml= file, use the following content and be sure to
update the =site= line with your username!
#+begin_src yaml
image: alpine/latest
oauth: pages.sr.ht/PAGES:RW
environment:
site: your-username.srht.site
tasks:
- package: |
cd $site
tar -cvz . > ../site.tar.gz
- upload: |
acurl -f https://pages.sr.ht/publish/$site -Fcontent=@site.tar.gz -Fprotocol=GEMINI
#+end_src
For the =index.gmi= file, put whatever you want in there and save it.
You could even just copy and paste the Gemtext cheatsheet.
If you want to serve both HTML and Gemini files from this repository,
just add a second command to the =upload= section:
#+begin_src yaml
- upload: |
acurl -f https://pages.sr.ht/publish/$site -Fcontent=@site.tar.gz -Fprotocol=GEMINI
acurl -f https://pages.sr.ht/publish/$site -Fcontent=@site.tar.gz
#+end_src
Lastly, commit your changes and push them to the remote repo.
#+begin_src sh
git add .; git commit -m "initial commit"; git push --set-upstream origin HEAD
#+end_src
If you've successfully created the files with the proper format, you'll
see the terminal print a message that lets you know where the automatic
build is taking place. For example, here's what the terminal tells me:
#+begin_src sh
remote: Build started:
remote: https://builds.sr.ht/~user/job/689803 [.build.yml]
#+end_src
Now that you've properly built your Sourcehut page, you can browse to
your-username.srht.site in a Gemini browser and view the final results.
Take a look at the image below for my Sourcehut Gemini capsule.
#+caption: Gemini page on the amfora browser
[[https://img.cleberg.net/blog/20210328-launching-a-gemini-capsule/amfora.png]]
|
