Shouldn't the readme first explain what this project is about? How would I know if this is relevant for me/my work. Not trying to be obtuse, I am fairly new to CS and I would like to understand what I am looking at and how I could use it in future.
It's source code and infrastructure as code for the services that are described at pico.sh, for self-hosting, development, etc.
Some of the services appear to live directly within this repo. There's also separate apps (that are separately packaged via docker, and referenced in the docker compose) elsewhere in the same GitHub organization
See the docker-compose.yml for an overview of the services that this repo is meant to enable running. Or if you click the link to their site, pico.sh, and hit Getting Started, there's a lot more documentation there.
From the top of the readme, it says to look at the docs on the website pico.sh. So, the readme does give info on what it's for by referring you to the authoritative location for that info. Should the source code README explain what it is? Maybe if the github repo was meant to be the main interaction for the project, but it's obvious from following that link that it's not meant to be, given the attention they put into that site.
I think what you're actually doing (whether you realize it or not) is criticizing the person who submitted this project's choice to link the github repo instead of the main site, which is a valid criticism, but that isn't really a fault of the project IMO.
> Should the source code README explain what it is?
Yes, at least one sentence at the top. Linking to a website containing several "something.sh" titles leading to multiple pages with proper one-sentence descriptions is a silly treasure hunt.
I wasn't that interested, gave up after 2 pages and my take is still "they're re-using popular text editor's name, whatever this does".
I'm not sure why you think a single sentence at the top is better than a link to website that documents it, nor why you think it's the job of the source repo to explain what it is instead of how to build it. Sure, in some cases you might want that, but not every source repo is meant to be he onboarding location for people, where they learn what something is and what it's for.
It's sort of like expecting assembly instructions to be full of marketing copy about why you want to use the product and why it was made. Presumably, when you're looking at the instruction manual, you're already past that point. Just because someone did the equivalent of handing you an instruction manual does not mean that instruction manual has a major shortcoming by not explaining all the wonderful ways the product it builds can help you. You were given the wrong material without context.
It’s not just you. Looks like a bunch of scripts for web hosting? But I shouldn’t have to click through several layers for the first real clue, and no I don’t want to “Get Started!” with no prior information.
I think you underestimate the cost involved of creating and supporting something more than barebones.
Building a barebones platform for people who are largely self sufficient is cheap. Building a full fat platform for people who need more hand holding, is a bit more costly.
Spent a little time poking around to see what this is...
It's a bare-bones hosting service with a limited free tier (25MB asset storage), and a cheap premium tier (10GB asset storage for $2/month).
The big selling point is this:
"The secret ingredient to all our pico services is how we let users publish changes to their sites without needing to install anything. We accomplish this with what is colloquially termed SSH Apps. By using the SSH protocol and golang's implementation of SSH, we can create golang binaries that interface with SSH in unique ways."
They offer these pre-built services + client side tools
- static hosting (pgs.sh for normal static hosting, prose.sh adds blog platform)
- expose your local/home webserver to the internet (tuns.sh)
It's nice to know that. Could not tell that easily by reading the entire readme or the linked docs. If founders/devs are reading this, it'd probably be a good idea to make it obvious what this is for up front. Even just a one paragraph explainer like the comment I'm responding to for context could help people know if this is even relevant to them.
I think the main thing here is https://pico.sh/pgs which works well as a landing page - it's a static site host that you push files to using rsync and can manage using ssh. Gives the impression someone built this for themselves and then rolled it out to the general public. At least, the subset of it that isn't overly frightened of a terminal.
The GitHub page (and frankly, to a degree also the landing pages) do not explain very well why the project is so great.
Basically, pico.sh is a collection of minimal web services that you control via SSH. Since it uses your SSH key as identifier, there is no registration process needed. For instance, setting up a blog with prose.sh[^1] took me less than a minute.
There is no real GUI, you manage everything via the terminal. Since publishing stuff is just running a one-liner in shell,[^2] it is very simple to automate/customize stuff. Copied the one-liner into the shell commands plugin for Obsidian, and I was able to publish notes from Obsidian to my prose.sh blog with one hotkey.
There isn't really much more to it than I already wrote. It's minimal, local, markdown-based, and terminal-friendly. There is some basic customizability (special files to add a footer and/or a header), and that's it.
If you already have SSH set up (e.g. for GitHub), it really just takes a minute to get started, so I'd just give it a try and see whether this is the right thing for you.
I wrote my crappy script in anger at how poorly passwords integrate with gitops workflows. It's just a matter of making a nice UX for this flow to make it useful. All the libs you need for this are already done in go.
Interesting script! Really dig how it harvest pubkeys from a GitHub org. Does it support fine grained control of which secrets are available for decryption by a particular key?
You can further edit .sops.yaml(eg have multiple of them) and decide how you split secrets in your directory tree to further customize who can decrypt the secrets.
Thanks for posting. There are many things down this rabbithole and I hadn't seen pico.sh before.
The github repo has the sources for the backend, but the services themselves are accessible over https at eg: pico.sh, prose.sh, pastes.sh, pgs.sh
Onboarding to the free stuff is easy by sshing with an existirng Identity to pico.sh, which creates subdomains for you at the various services above.
The central idea is to expose a whole bunch of simple services using SSH for auth and for tunneling, and occasionally rsync as a file-transport. While this may not be an efficient way to run high-traffic services, it's a great way to stand up simple back-of-house tools and I wish more people were doing things like this.
Love the aesthetic and the commitment to proving this out.
I think they use “hacker” in the sense of a person who is curious about how systems works and will expend their own effort to understanding it.
Based on the comments on this thread, you likely are, given that the vast majority of people are dunking on how difficult it is to understand, while you’ve distilled it down to a workflow already.
Or to put it another way, you underestimate yourself, and possibly overestimate everyone else.
