# 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.