How to get started? (missing doc?)

[deg]

tl;dr - The startup docs have some gaps that are hurting me as a newbie.

I'm taking a first look at Vase, and have never used Datomic. I'm trying to find the easiest path to a minimal working example which, I guess, would include a running service that I can deploy locally or to some cloud service, and that can persist data in the face of a system reboot.

I did 'lein new vase your-first-api', and am indeed up and seeing Hello World.

I don't know if I already have a database configured, nor how to test. I see the following lines in the docs:

In docs/your_first_api.md:

... be sure you have a Datomic transactor running. See ... docs ... [T]he template project uses Datomic Pro. (You can change the project.clj dependency to use Datomic Free. ...)

But:

• I did not do any Datomic setup, yet something seems to be working. Do I need to do more, or is Vase complete as is.
• I don't have a copy of Datamic Pro. Yet, I did not change anything to use Datamic Free.
• There is no mention of Datomic in my project.clj.

And, then, once I get Datomic setup, how I understand that it starts as an in-memory database. How do I persist to disk? This is just a hobbyist project now, so I'm fine with something simple. I see http://docs.datomic.com/backup.html, which may be all I need, but I don't yet see what/how I need to integrate into my project.

And, maybe out of scope, but it would be good to have a few lines about how to deploy to a production server.

[mtnygard]

Hi @deg, sorry to hear that our docs aren't helping you through the getting started experience. Thanks for the feedback. I'm going to leave this issue open while we try to address your points in the docs.

In the meantime, if you're able to join the Clojurians slack team, I can help you out today on the #pedestal channel.

[ohpauleez]

Hi @deg, thanks for reaching out with the issue and asking for help.

As @mtnygard mentioned, there is some support in the #pedestal channel on the Clojurians slack. You can also use the Pedestal mailing list, but feedback will be a bit slower.

Out of curiosity, how did you discover Vase?

Some immediate answers:

Vase ships with Datomic-Free bundled into the deps and the default service created is using an in-memory database. That's fine for getting started, but you'll want a durable database for production.

Vase is a thin layer on top of Pedestal, so a Vase application is deployed like a Pedestal application. For many, an "uberjar" is the easiest approach:

1. lein uberjar
2. java -jar target/myproject-0.0.1-SNAPSHOT-standalone.jar

[mtnygard]

Note to self: readme indicates Vase is "totally self-contained." That's true but only for dev with in-memory. We should add a doc about moving from in-memory to on-disk.

[mtnygard]

Also, we should make sure our language about the tiers matches the current names on datomic.com.

[deg]

IMHO, since Vase wants to be self-contained, it should also link to documentation that exists elsewhere, to make things easier for newcomers (or maybe even duplicate key parts).

Basically, it feels to me that the current docs are aimed at an audience already very familiar with Pedestal and Datomic.

But, even among us current Clojure developers -- and certainly in the wider world -- there are many people for whom Vase seems like a great framework for creating a server, even though we lack any real exposure yet to Pedestal or Clojure.

Areas I'd love to see documented here include:

• A more linear set of docs, that I can read through easily, rather than the current bushy tree where it's not obvious what to read first, nor even what docs may be less current
• How to setup my dev environemnt, including integration with Emacs/Cider (and other tools too, I suppose)
• Overview of the sample apps
• Some background philosophy about predominantly server solutions, like Vase appears to be; vs frameworks that merge CLJ and CLJS into one complex lein-declared project
• Links to the most important Pedestal and Datomic docs.
• Etc.

[deg]

Capturing something I just wrote on the Slack channel, 'cuz it lists a few places to fix up the docs:

deg [3:07 PM]
I'm trying to find a set of docs to read, to understand the full Pedestal picture. I'm now five minutes into the process; probably close to the target; but frustrated/amused at the search. Recording notes here, both to vent and in the hope that this helps a future cleanup.

1. A Google search took me, somehow, to https://github.com/pedestal/app-tutorial. Looks great; starts with "This tutorial will guide you step-by-step through pedestal-app in its entirety." But, then I noticed that this project has not been updated in four years!
2. Next, I found https://github.com/pedestal/pedestal-docs. But, quickly realized that this is the toolset for building the docs, not the droid I was looking for.
3. But the README.md does not have a link to where I should go for the docs. [Later: I now see there is a link, hidden at the top of the page above the GitHub status and file list. I didn't even know that GitHub lets projects write to there. So, ok, I should know to to go to http://pedestal.io. But, I missed that clue, so bear with me as I wander]
4. I go back to https://github.com/pedestal/pedestal, and read the README.md to the end. Hurrah, I find links to "Documentation / Pedestal documentation / ... The latest API Docs", with two nice links.
5. So, I follow them. The API link looks useful for later, but I want to read some descriptions first. So, I save it to the side. The Pedestal Documentation link takes me to https://github.com/pedestal/pedestal/tree/master/guides/documentation. Looks good!
6. I read the first page. Nice intro. And, there is even a link at the bottom to the next page. This looks like exactly what I want: a linear guide through the key docs.
7. So, I follow the link to the next page: https://github.com/pedestal/pedestal/blob/master/guides/documentation/hello-world-service.md. Wham, Boof. "Obsolete Guide". But, at least there is a link here to http://pedestal.io/guides/hello-world, so I now discover pedestal.io.

End of saga, I hope!

[ohpauleez]

Hi @deg -- Sorry for getting tripped up. The Pedestal docs have moved a few a times, but are now in a dedicated spot -- being served at pedestal.io and the content in a dedicated github repo. You should be using that site and the Pedestal Samples for all of your learning.

As you find broken links (or links to old content), feel free to open an issue or pull-request directly on the Pedestal project. I'll patch up the issue with the README right now.

[mtnygard]

I wonder if we can do some SEO work to displace those old links. New blogs linking to pedestal.io?

Whoops, just noticed we're still in the Vase repo. Comments about Pedestal documentation should be redirected to http://github.com/pedestal/pedestal-docs.

[ohpauleez]

If we can find a way to generate hard 302's from github, that would fix the navigation issues and the SEO issues. Not sure that's possible.