content/blog/2021-03-28-gemini-capsule.org

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