Set up is more complicated than forking

[waldoj]

GitHub doesn't deploy to GitHub Pages after a fork, it turns out—it's necessary to make a commit to that fork first. (This is contra to the setup instructions.) Unless there's a way around this, I imagine that the instructions will have to modified to include a step in which the repo is altered in some way, e.g. a dataset is added (which I appreciate isn't yet supported).

[timwis]

Oh no! That's a shame. We can't even rely on the setup page to make a commit because the setup page doesn't exist yet. A couple ideas come to mind:

1. Have them edit some placebo file using github's interface, like a file called activate, and type something in it
2. Take an approach similar to waffle.io or gitter, where we have some bot that sends you a pull request. The bot could be activated when the repo is forked, and send an empty commit that they could then merge. This would require a central "jkan controlled" server, but only for ease-of-use purposes

Thanks for catching this, I swore it worked before...

[timwis]

Maybe @benbalter knows a trick to get github pages to build automatically on a new fork?

[timwis]

For now, I've updated the getting started instructions to direct users to make a change to _config.yml so at least the docs are accurate

[benbalter]

https://copy-to.herokuapp.com/ may help.

[timwis]

@benbalter you're remarkable! Thanks!

[timwis]

Just thought of another idea - perhaps we combine the /setup/ page with @benbalter's approach. What if the jkan.io "Get Started" docs explain how to do the install manually (fork, modify _config.yml to change title/description, add in auth credentials), but also offer the "wizard" that is currently on the /setup/ page of the JKAN site? This, I think, would make the setup process easier and remove the "setup wizard" from the JKAN codebase (it would live on jkan-website instead).

The result would be a user could go to jkan.io and under the "Get Started" section, they could click a button that would log them in through github, fork JKAN, let them enter their auth credentials, and save them in the _config.yml file. When they're done, their site is completely setup.

[timwis]

Okay guys, I've implemented the latter idea. Before I deploy it, would someone mind walking through it and verifying everything works for you too, any comments on the experience, etc.? https://jkan.surge.sh
@waldoj @JJediny @pezholio

[pezholio]

@timwis I get redirected to localhost:4000 when logging in with Github. I guess you need to change the tokens?

[timwis]

Hah! doh :P Should be fixed now, thanks @pezholio

[waldoj]

Liveblogged:

• During Step 1, I was momentarily puzzled when GitHub sent me back to jkan.surge.sh, but to the top of the page. If you can have that go to e.g. jkan.surge.sh/#step1, I think that would help.
• I just got to Step 3 and thought "whoa, this is involved."
• Placeholder text in input boxes is light gray, but the completed text is also light gray, which indicates that it's still placeholder text. Presumably the entered text should be black.
• The login link in the deployed site is covered up by the "Fork me on GitHub" banner, making it hard to click.
• The login link yields a GitHub 404.

[pezholio]

Couple of thoughts:

• You don't need to add the callback URL when setting up the app in Github - this is automatically populated with the homepage url if you leave it blank. There's no harm putting both in, but it just removes another vector for error I guess *
• You can also add params to the deploy button URL in the format env[OAUTH_CLIENT_ID]=whatever and env[OAUTH_CLIENT_SECRET]=whatever, which might remove some potential pain points, so all people have to do is enter their app name. Would also mean if someone accidentally closed the tab with their app details they won't have to go hunting around for the secret
• I have a custom domain set up, so my JKAN instance is acutally at http://blog.pezholio.co.uk/jkan, so I had to tweak my oauth details - may be why @waldoj got a 404. I'm probably an edge case, but it might be worth pointing that out

* Sidebar: I guess it would be nice to bypass this altogether using the Github API, but I guess creating applications via the API isn't possible (for probably very sensible reasons!)

[waldoj]

I have a custom domain set up, so my JKAN instance is acutally at http://blog.pezholio.co.uk/jkan, so I had to tweak my oauth details - may be why @waldoj got a 404.

I just went with the default of waldoj.github.io/jkan.

[pezholio]

@waldoj - Ah yes. I think you need to add a closing slash - I noticed that too first time round, but forgot to mention it

[timwis]

Thanks guys, great feedback!

[timwis]

FYI, the github login now redirects to the #get-started anchor and a trailing slash is used on the callback url instruction. I've broken the heroku deploy env vars idea out into its own issue. Thanks for testing, guys! Now to take out the /setup/ logic from the JKAN codebase.