cmc/cleberg.net

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