[Improvement] [Request] Expand the Gemini CGI subsection #106

New Issue

zinricky · 2021-09-18T14:56:36Z

zinricky commented

2021-09-18 14:56:36 +00:00

I’m having trouble finding a consistent and complete guide to use CGI within the Gemini environment. What I ususally find is something along the lines of “you can use CGIs”.
It would be awesome to have the following things explained more in detail:

where to put CGIs;
how to make the server call them;
what programs can the CGIs use effectively;
more basic examples.

I’m having trouble finding a consistent and complete guide to use CGI within the Gemini environment. What I ususally find is something along the lines of “you can use CGIs”. It would be awesome to have the following things explained more in detail: - [x] where to put CGIs; - [x] how to make the server call them; - [x] what programs can the CGIs use effectively; - [ ] more basic examples.

jan6 commented

2021-09-18 15:45:51 +00:00

fun fact, you can actually use gemini keys with cgi, on ~team, but I've not seen ANYTHING mention it, you can see the env the cgi scripts see at gemini://tilde.team/~jan6/cert/, using a key adds some variables

but unlike http, you can put gemini cgi scripts ANYWHERE

you can have a script.gmi, you can have a script.cgi, filename, extention, and location don't matter, you can have script.txt be a cgi script if you so desire, as long as it's executable and outputs correct format

it also means that if you name a script index.gmi, then it will be shown instead of the file listing, which can be quite useful sometimes

since it's plain old CGI, the server calls them each time someone wants to view that page, and you don't keep any data between the runs

if you meant "what languages can the CGI scripts be written in" then answer is "any that can read environment variables" (including shell scripts, python, nodejs, C, etc.)
if you mean "what programs can a CGI script call" then answer is "literally whatever you wish"

the format is super simple, after all, you just need to print out a gemini header (such as "20 text/gemini\r\n" where \r\n are the newline characters, to output a normal gemini page), and then whatever you want to be on the page, you can read environment variables to use extra information, but simple scripts don't even need to do that (mainly useful when you want the script to accept input, or read certs, or be aware of what location or name it's called with)

an example shell script that prints out everything it has access to, you can save it as env.cgi for example, (notice how ``` cannot be in normal double-quotes, because it's a shell script)

#!/bin/sh
printf "20 text/gemini\r\n"
echo "# the script's environment:"
echo "## I'm running on ${SERVER_NAME}"
echo '``` script environment'
env
echo '```'

and here's the equivalent script in python:

#!/usr/bin/env python3
import os
print("20 text/gemini",end="\r\n")
print("# the script's environment:")
print("## I'm running on "+os.environ["SERVER_NAME"])
print("``` script environment")
for i in os.environ.keys():
    print(f"{i}={os.environ[i]}")
print("```")

I'm no good at making easily understandable wiki pages, but I think I gave enough info for you, or someone else, to make one

fun fact, you can actually use gemini keys with cgi, on ~team, but I've not seen ANYTHING mention it, you can see the env the cgi scripts see at [gemini://tilde.team/~jan6/cert/](gemini://tilde.team/~jan6/cert/), using a key adds some variables but unlike http, you can put gemini cgi scripts ANYWHERE you can have a `script.gmi`, you can have a `script.cgi`, filename, extention, and location don't matter, you can have script.txt be a cgi script if you so desire, as long as it's executable and outputs correct format it also means that if you name a script `index.gmi`, then it will be shown instead of the file listing, which can be quite useful sometimes since it's plain old CGI, the server calls them each time someone wants to view that page, and you don't keep any data between the runs if you meant "what languages can the CGI scripts be written in" then answer is "any that can read environment variables" (including shell scripts, python, nodejs, C, etc.) if you mean "what programs can a CGI script call" then answer is "literally whatever you wish" the format is super simple, after all, you just need to print out a gemini header (such as "20 text/gemini\r\n" where \r\n are the newline characters, to output a normal gemini page), and then whatever you want to be on the page, you can read environment variables to use extra information, but simple scripts don't even need to do that (mainly useful when you want the script to accept input, or read certs, or be aware of what location or name it's called with) an example shell script that prints out everything it has access to, you can save it as env.cgi for example, (notice how ``` cannot be in normal double-quotes, because it's a shell script) #!/bin/sh printf "20 text/gemini\r\n" echo "# the script's environment:" echo "## I'm running on ${SERVER_NAME}" echo '``` script environment' env echo '```' and here's the equivalent script in python: #!/usr/bin/env python3 import os print("20 text/gemini",end="\r\n") print("# the script's environment:") print("## I'm running on "+os.environ["SERVER_NAME"]) print("``` script environment") for i in os.environ.keys(): print(f"{i}={os.environ[i]}") print("```") I'm no good at making easily understandable wiki pages, but I think I gave enough info for you, or someone else, to make one

👍 3

khuxkm self-assigned this 2021-09-20 23:23:33 +00:00

khuxkm commented

2021-09-20 23:23:52 +00:00

I'll write this in a couple days as soon as my schedule clears up. (if ben or cmccabe or someone else wants to do it in that time then so be it)

👍 2

ben commented

2022-07-05 20:54:52 +00:00

@khuxkm any updates on this?