How to change the index page?

[brylie]

Story

As an API Umbrella administrator
I would like to change the appearance of the portal front page
So that I can add specific colors, text, images, and other details for our particular instance

Specifics

We have a designer who has created a bootstrap template that we would like to use as our portal page. Where do we put this template so that it will be displayed instead of the default API Umbrella page? What file do we edit if we want to change the default API Umbrella page?

[GUI]

The public website content comes from the api-umbrella-static-site repo. In the development setup this will be checked out in the workspace/static-site directory.

This uses middleman as a static site generator. The general idea is that you can host the site on GitHub Pages, or any other static HTML hosting location (S3 bucket, etc). The website content is inside the source directory, and Middleman's docs go into more detail about how the layouts and templates work.

However, if you'd like to use something besides Middleman for your website content, you can do that instead. This functionality isn't totally flushed out, but to start you would modify the static_site configuration inside /etc/api-umbrella/api-umbrella.yml to point to the host and port you want to proxy your public website content to. So, for example, let's say you wanted to use wordpress and it was running on the same server on port 8080, you could proxy to that like:

static_site:
  host: 127.0.0.1
  port: 8080

This same proxying configuration would also be used if you wanted to host things on github pages.

The one major caveat with either approach (using Middleman or some other CMS of your choosing), is that you'll currently face some hurdles in customizing the site if you want to introduce new webpage content. One of the first things the stack does when accepting an incoming request is determine where to send the request (is the request for an API, or for the admin tool, or for the website?). Right now, we have a hard-coded list of URL prefixes that we route to this public website content. This consists of paths like the home page or /docs* (you can see the full list). But this hard-coded list obviously becomes problematic if you want to add new website content at a new URL paths. This is on our radar and we're looking to fix this so there's not this hardcoded list: 18F/api.data.gov#146

In the meantime, there's a couple quick and dirty options:

• Edit this line in templates/etc/nginx/router.conf.hbs to adjust path prefixes you're matching (this will work fine, but just be careful if you're doing this and using the binary package installers, since your changes will likely be wiped out the next time you upgrade the api-umbrella package).
• Stick new content under subdirectories of the paths we're already routing. So for example, if you want to add a terms & conditions page like you mentioned on Add 'terms & conditions' page #65, maybe putting that content under /signup/terms (since we are routing /signup/*).

Neither approach is really ideal, but they might allow you start playing around in the near-term. And as I mentioned, this issue is definitely something we're looking to fix soon-ish.

[brylie]

Issue #56 mentions that the existing /terms page does not exist.

It seems like Umbrella may need some basic functionality for content management for a number of use cases. E.g.

• Modifying the /terms page
• Modifying the /signup page
• Basic branding (e.g. changing 'Your API Site Name')

[brylie]

Specifically, what file/folder do we edit to change the static front page? I.e. on production, from where are the static files served?

[brylie]

I found a couple of locations with the following command:

$ sudo grep -rl "Your API Site Name" /
/opt/api-umbrella/embedded/apps/static-site/releases/.../source/....erb
/opt/api-umbrella/embedded/apps/static-site/releases/.../build/....html
...
...

If we change the .erb file, how do we trigger a build of the site? Can we just edit the index.html directly?

[GUI]

Well, this is absurdly belated (sorry!), but here's finally some documentation on how to configure website backends: https://api-umbrella.readthedocs.io/en/latest/admin/website-backends.html Website backends were originally added in the v0.8.0 release (released on 2015-04-26) as a way to make all this easier:

• Any non-API URL will get routed to the website backend (so there shouldn't be some of the hurdles I originally outlined in adding new content at new paths).
• Different websites can be served for different hostnames.
• There's an interface in the admin for defining the website backends.

[brylie]

Well, this feature request pretty much spawned the APInf project, so "water under the bridge". In a somewhat funny twist, we are currently working on/planning features in APInf that allow admin users to customize the front page. 😆