144 lines
4.3 KiB
Markdown
144 lines
4.3 KiB
Markdown
# spartan
|
|
|
|
spartan is a relatively new internet protocol that is somewhat similar to
|
|
[gemini](gemini.html) but a lot of simpler to play with because of the lack of
|
|
TLS.
|
|
|
|
like gemini, it is much lighter than the web and has a much smaller user base.
|
|
|
|
first time hearing about spartan? you should check out its homepage:
|
|
[gemini://spartan.mozz.us](https://portal.mozz.us/gemini/spartan.mozz.us)
|
|
|
|
at tilde.cafe, we run a spartan server
|
|
([spsrv](https://tildegit.org/hedy/spsrv)), and all ~cafe users can have their
|
|
own files hosted on spartan by putting content in their `~/public_spartan`
|
|
directory.
|
|
|
|
your spartan site will then be live at both spartan://tilde.cafe/~username/ and
|
|
spartan://username.tilde.cafe
|
|
|
|
the `~/public_spartan` directory is not created by default. use `mkdir
|
|
~/public_spartan` to create it, then you can start building your site!
|
|
|
|
spartan uses gemtext markup (instead of, say, html for the web)
|
|
for more information about how you write gemtext, check out the [Introduction
|
|
to Gemtext Markup](https://gemini.circumlunar.space/docs/gemtext.gmi), there is
|
|
also a [cheatsheet](https://gemini.circumlunar.space/docs/cheatsheet.gmi).
|
|
|
|
to browse spartan content, you will need a client or a [web
|
|
proxy](https://portal.mozz.us/spartan/mozz.us).
|
|
|
|
|
|
## clients
|
|
|
|
- [gelim](https://sr.ht/~hedy/gelim): try `gelim spartan://tilde.cafe` at the
|
|
terminal
|
|
- or just use the web proxy [portal.mozz.us](https://portal.mozz.us/spartan/mozz.us)
|
|
|
|
|
|
## CGI
|
|
|
|
make sure you set the correct **shebang** and make the file **executable**.
|
|
|
|
then, print the status and type per the [spartan
|
|
spec](https://portal.mozz.us/spartan/spartan.mozz.us): here's a simple example
|
|
in sh
|
|
|
|
#!/bin/sh
|
|
printf "2 text/gemini\r\n"
|
|
echo "hello world"
|
|
|
|
note that the first line **must send `\r\n`**
|
|
|
|
if you want to debug your script, you can redirect your stderr into a file, if
|
|
you use shell scripts, you'd do it like this:
|
|
|
|
#!/bin/sh
|
|
exec 2>/tmp/my_spartan_debug.txt
|
|
printf "2 text/gemini\r\n"
|
|
echo "hello world"
|
|
|
|
keep in mind that all cgi scripts run under a single user ("spartan"), so it
|
|
might not have permission to run scripts, or write files, that you can
|
|
|
|
also be careful about what the scripts can write, because there's nothing
|
|
preventing someone else from overwriting your files, with their scripts!
|
|
|
|
you can also check for the user's input. for example, you your `index.gmi` you
|
|
can have a input prompt:
|
|
|
|
|
|
=: echo.sh send some input
|
|
|
|
then in `echo.sh`:
|
|
|
|
#!/usr/bin/env sh
|
|
|
|
printf "2 application/octet-stream\r\n"
|
|
cat /dev/stdin
|
|
|
|
try visiting your spartan page, enter some input on that link line and see the
|
|
result!
|
|
|
|
alternatively you could send input directly in gelim:
|
|
|
|
gelim spartan://username.tilde.cafe/echo.sh -Ii 'hello!'
|
|
|
|
(note: `-I` is so gelim quits immediately after displaying output, `-i` is for
|
|
sending the input)
|
|
|
|
|
|
### greeter example
|
|
|
|
what makes spartan distinct from gemini is the ability to send in data together
|
|
with any spartan request. for example, try doing:
|
|
|
|
gelim spartan://mozz.us/echo -Ii 'hello spartan'
|
|
|
|
this sends the data "hello spartan" along to the request, and the `/echo` path
|
|
of `mozz.us` server would then echo back whatever you've sent it, in this case,
|
|
"hello spartan".
|
|
|
|
you can make your own echo CGI script too! first, create a new executable file
|
|
for your script:
|
|
|
|
mkdir ~/public_spartan
|
|
cd ~/public_spartan
|
|
touch echo.sh
|
|
chmod o+x echo.sh
|
|
|
|
then open the script with the editor of your choice and add the following:
|
|
|
|
#!/usr/bin/env sh
|
|
|
|
printf "2 application/octet-stream\r\n"
|
|
cat /dev/stdin
|
|
|
|
save the script, then try it out!
|
|
|
|
gelim spartan://username.tilde.cafe/echo.sh -Ii 'this is my input'
|
|
|
|
it's that easy :) remember to replace `username` with your username and
|
|
`echo.sh` to the path of your script
|
|
|
|
next, let's try building a simple greeter program.
|
|
|
|
create a new file that will hold your script, make it executable, then put the
|
|
following in:
|
|
|
|
#!/usr/bin/env sh
|
|
|
|
printf "2 text/plain\r\n"
|
|
name=$(cat /dev/stdin)
|
|
echo "Hello, ${name:-World}!"
|
|
|
|
simple, right? let's try it out!
|
|
|
|
gelim spartan://username.tilde.cafe/greet.sh -Ii 'yourname'
|
|
|
|
replace `username` with your username, `greet.sh` with the path to your script,
|
|
and `yourname` to anything you like.
|
|
|
|
feel free to drop by `#spartan` or `#cafe` on [tilde.chat irc](irc.html) if you have
|
|
questions.
|