When you’re spending your days (and nights) developing the best cloud management platform possible, blogging consistently is hard. That said, we’re redoubling our efforts to get content out semi-regularly, even if it’s just to post something simple and (hopefully) helpful. To that end, I’d like to discuss setting up Github pages with a backend.
The Problem
Github.com allows you to host static content via its pages feature. This is fantastic because it makes it trivial to create, deploy, and update a website. This is how https://sunshower.io is hosted.
But what if you wanted to interact with, say, a database, to track signups? Furthermore, what if you wanted to do it all over TLS? This tutorial presumes that your registrar is AWS and your DNS is configured through Route53.
Set up Github DNS Alias Records For Github Pages
This one’s easy: In your Route53 Hosted Zone, create an A record that points to Github Page’s DNS servers:
>185.199.110.153
> 185.199.109.153
> 185.199.108.153
> 185.199.111.153
Then, check in a file in your pages repository under /docs called CNAME containing your DNS name (e.g. sunshower.io)
Push that sucker to master and you should have a bouncing baby site!
Publish your backend with the correct CORS Preflights
We pretty much just have a plugin for Sunshower.io that registers unactivated users. Create an EC2 webserver/Lambda function/whatever to handle your requests. The thing you have to note here is that your backend will have to support preflight requests. A preflight request is an OPTIONS request that your server understands, and responds with the set of cross-origin resource sharing (CORS ) that your backend understands.
This is because your page, hosted at a Github IP, will be making requests to Amazon IPs, even though both are subdomains beneath your top-level domain. For a JAX-RS service at, say, https://mysite.com:8443/myservice, you will need two methods:
@Path("myservice")
@Produces({
MediaType.APPLICATION_JSON,
MediaType.APPLICATION_XML,
})
@Consumes({
MediaType.APPLICATION_JSON,
MediaType.APPLICATION_XML,
})
public interface SignupEndpoint {
@POST
RegistrationConfirmationElement signup(RegistrationRequestElement request);
@OPTIONS
Response getOptions();
}
Note that there must be an @OPTIONS method for each actual conversation method that you want to interact with (e.g. the @POST method here). What will happen is that a preflight will be made to the same path as the request, and the server will respond with whether that request is allowed. You can widen the scope of @OPTIONS responses, but you should have a pretty good reason for doing so.
The actual @OPTIONS method will look something like:
@Override
public Response getOptions() {
return Response.status(Response.Status.OK)
.allow("POST")
.header("Access-Control-Allow-Origin", "*")
.header("Access-Control-Allow-Methods", "POST, OPTIONS")
.header("Access-Control-Max-Age", 1000)
.header("Access-Control-Allow-Headers", "origin, x-csrftoken, content-type, accept")
.build();
}
where the allow value and Access-Control-Allow-Methods values align with the request type of the actual backend methods.
Set up a SSL-enabled ELB
The first thing to do here is to create a certificate using AWS’s wonderful Certificate Manager Service.
Request a certificate by navigating to Certificate Manager > Request a Certificate in the AWS Management Console. Request a public certificate, and then request it for the fully-qualified name that you want your backend to appear under (e.g. backend.sunshower.io). If you have access to any of the follow e-mail addresses at your domain:
- administrator@
your_domain_name - hostmaster@
your_domain_name - postmaster@
your_domain_name - webmaster@
your_domain_name - admin@
your_domain_name
then select e-mail verification, otherwise select DNS verification and proceed according to the instructions provided by AWS.
Once you’ve verified your certificate, create an elastic load balancer on whatever availability zones your backend spans. If you only have one instance in one availability zone (shame shame!), add that availability zone first. Create a listener targeting the port that your actual backend is listening on, and add a security group with an ingress port that corresponds to the port that you want your public-facing backend to listen on (for instance, if you want your backend to respond to requests to https://backend.sunshower.io, configure your ingress to be 443.
From there, configure a target that points to your actual backend. If your backend is hosted on EC2 instances, select the instance type for the target, otherwise select ip. Reference the IP/instances of your backend and create the ELB.
Configure a DNS A Record for your ELB
The last thing we need to do is create an A Record that points to your ELB. If, previously, you requested a TLS certificate for backend.mysite.com, you’ll want to create an A-record whose name is backend, alias=true, with an alias target that is the ELB you created in the previous step. Save that sucker and you are good to go!