AstroNav is a tool for finding shortest-path walking directions (a functionality that Google supports in their API but doesn't seem to surface in any GUIs). It was specifically created for taking on Goruck Star Course events, but could also be used for other stuff, I suppose.
An AAR (After-Action Report) from the first time it was put to the test is up at donnorum.com and is fairly entertaining if you like reading about people making terrible life decisions.
If this sounds useful to you, you're welcome to use our stack at astronav.drunkenrobotlabs.org (although it'll likely be unreachable to the general public while we're competing because I'm a competitive jerk). The instructions for setting up your own stack are not for novices.
This is moderately complicated and not something the average user will want/need/be able to do, as one stack can be used by a bunch of people. If you encounter problems or have suggestions on improving the instructions, just let me know (although I may or may not respond, depending on how busy I am). Likewise, feel free to submit pull requests if you think improvements could be made.
Important note: All of the AWS links below default to using "us-east-1" (Northern Virginia) as the region, as that's the default in most places and also conveniently the region closest to where I live. However, this should work in pretty much any region if you change all the links.
I'm assuming you already have one, as you're reading this on GitHub, but if not, create one. It can just be a free one, no need for any fancy features.
Google "Create an AWS account". Other people have written far better guides than I ever could.
If you want, you can have your stack accessible at some fancy name like we do. If you want to do this, you need to own a domain name. You can buy one through a number of different sites. I use Google Domains, but you can also use AWS (I think), GoDaddy, or a bunch of others.
If you do this, you need to create a Route53 Hosted Zone for it. Docs are here. If it's not a domain registered through AWS, you'll need to update the DNS settings such that it uses the Route53 DNS servers. This has the potential to break stuff and I'm not a routing expert, so some googling to find instructions is required.
Once the Route53 Hosted Zone is set up, you'll need to request a certificate for the subdomain you want to use for the stack. Docs are here. I recommend using the console instead of the CLI because the console will let you update the Route53 stuff necessary to validate ownership of the domain in just a couple clicks.
After all that, continue with the following steps.
Google "Create a Google Cloud Platform account". As before, other people have written far better guides than I ever could.
Go here, click "Get started", follow the prompts. You'll need to enable the Maps and Routes products, I think.
You'll eventually need to go to the Directions API Credentials page in the console and create two API credentials. I'll be calling them the GmapsSecretKey and GmapsPublicKey. Once you generate each one, copy the blob of text under "API key". You'll need it when you create the CloudFormation stack later.
This API key will have no restrictions. It will never be shown to customers.
The GmapsPublicKey will have an Application Restriction of "HTTP referrers (web sites)".
If you're using a custom domain name, add the referrer "https://whatever.your.domain.is/\" (in our case, it's "https://astronav.drunkenrobotlabs.org/\").
If you aren't, and are going to just use the autogenerated url, add "https://*.execute-api.us-east-1.amazonaws.com/*". This can later be scoped down to the specific URL prefix that gets generated for your stack, if you want to be extra safe.
Adding both is totally fine if you aren't sure which route you'll go or if you might switch back and forth.
Fork this repo into your GitHub account. No need to make any changes to the code, it just needs to be in your account for permissions-related reasons.
You need to be able to upload the codepipeline-lambda.cf.json file in a later step, so either download that file, or, more likely, just clone the entire repo onto your computer.
Some manual work is required to enable the auth for this pipeline to talk to GitHub:
-Go to Settings/Developer settings/Personal access tokens in GitHub to create a new OAuth token.
-Click "Generate new token"
-In "Token description", put "AstroNav AWS CodeBuild/CodePipeline" or something else descriptive.
-Under "Select scopes", select "repo" and "admin:repo_hook"
-Click "Generate Token"
-Copy the token. Keep it secret, keep it safe, and provide it as an unencrypted input to your CF stacks. (Yeah, I know that means read access to your CF stack inputs is equivalent to admin access to all your GitHub repos. It's probably possible to instead use AWS Secrets Manager for it, but that costs money and I'm the only one with creds to my AWS account, so I haven't bothered investigating that yet.)
-Finally, follow the instructions in step 5 of "Create a Build Project (Console)" in the CodeBuild docs to directly give AWS access to GitHub. (And yeah, I know this is just giving AWS the same permissions as those given by the aforementioned OAuth token, but it's what seems to currently be required.)
Go here and upload the codepipeline-lambda.cf.json file from a couple steps ago. I usually name this stack -build (so in this case, astronav-build), but it cen be pretty much whatever you want as long as it isn't the same thing you specify for "ChildStackName" below.
For the parameters, enter the following:
BuildImage: Unless you know what you're doing, just leave this as "aws/codebuild/eb-python-3.4-amazonlinux-64:2.3.2"
BuildTimeout: Unless you know what you're doing, just leave this as 5.
ChildStackName: I recommend "astronav-master" (or whatever branch you're using), but it doesn't make much of a difference. If you specify an invalid name, it'll cause the stack to fail and you'll need to delete and recreate it.
GmapsPublicKey: From the previous step where you created Google API keys, this is the one with the Http Referrer restriction.
GmapsSecretKey: From the previous step where you created Google API keys, this is the one with no restrictions.
OAuthToken: This is the one you got from GitHub in the previous step.
PackageBranch: Whatever branch you're using.
PackageName: Unless you changed the name of the package, this should be "astronav".
UserName: Your GitHub username.
Click "Next" through the next couple pages. One of them will require you to check a box indicating that you understand the template is creating IAM resources. That's expected, just check the box and keep going.
Once the stack starts creating, just wait for it to finish. If it fails, investigate why. (If you can't figure it out, feel free to ask me, but I may not be able to offer much help, and I can almost certainly not offer any help quickly.) If it succeeds, keep going.
There should now be a pipeline on this page with the name that you entered for "ChildStackName" in the previous step. Click on it; there should be three steps: Pull_Source, Bundle_Lambda, and Update_CF_stack. If nothing seems to be happening, click the "Release Change" button up at the top.
If any of the steps fail, investigate why. If they all succeed, go to the API Gateway console. There should be a new API, again with the name that you earlier entered for ChildStackName. Click on it, then on "Stages", then on the stage "Prod". There should be a banner at the top that starts with "Invoke URL"; click on that link to go to your stack.
If you don't want to use a custom domain name, you're done.
This is only necessary if you want to use a fancy name that you own (e.g., https://astronav.drunkenrobotlabs.org) instead of the autogenerated one (e.g., https://abcde12345.execute-api.us-east-1.amazonaws.com/Prod), and only works if you completed optional step 2 earlier in the instructions.
Go to the API Gateway console and create a custom domain name entry for your domain name, then point it at the prod stage of your stack. The page has pretty good instructions, so follow those. Other docs are available here.
Once that's done, if you haven't already (some instructions include it, some don't), you need to create an alias for that domain name in Route53. Copy the Target Domain Name (something like abcdefgh.cloudfront.net), go to your Hosted Zone in the Route53 console, click Create Record Set. The name is your subdomain (in my case, "astronav"), the type is "A", select "Yes" for Alias, then enter the Target Domain Name under "Alias Target". Select "Save Record Set".
It'll take a while for all of that to flow through the internet tubes, but once that's done, you'll be able to use your stack from your fancy name.
Because this is software, it will inevitably break at exactly the wrong time (in my case, it broke literally the first time I tried to use it during an actual Star Course event). To debug failures, you can use the logs that appear in CloudWatch Logs. To see those, go to the CloudWatch Logs page, then click the group corresponding to your stack (the link includes the prefix "astronav", so if you changed the name, you'll need to search slightly differently, and if you didn't, it's likely that only one log group will show up).
Click that log group, then click "Search Log Group", then the filter "5m" to look at just the last 5 minutes of logs (or longer if necessary, or some specific time period when the failure occurred). Hopefully the info in there will give you an idea what went wrong and you can fix it.
If you followed this guide exactly and didn't change a bunch of stuff, any changes that you push to your git repo should automatically deploy through the CodePipeline. This makes it easy to fix bugs and also easy to cause bugs. If this isn't ideal, you can develop on a different branch than the one that your pipeline is watching, and only push to that branch when absolutely necessary.
You can also deploy updates outside of the normal CodePipeline using the tools in snkes. I haven't finished writing the first draft of the documentation so you likely can't figure out how to use them right now, but if you want to bash your head against them trying, you can clone and install them from that package, or they're available in PyPI using "pip install sneks".