Document how to run locally

[Steven Grimm]

Running the tool locally requires a fair bit of setup that isn’t really documented anywhere I can see. I managed to get it working but am filing this as an issue rather than a pull request because I expect I did it in a pretty suboptimal way (since I’m unfamiliar with Google App Engine app development).

First problem: To do OAuth logins, you need an HTTPS server, but the Google App Engine local development environment only does HTTP, so you need to put a proxy in front of it. If you’re already running Nginx or some other proxy, you can add rules to forward to port 8080, but I wasn’t, so I used a Docker image that self-signs a certificate and launches a proxy. I had to modify it a bit to pass the correct hostname, though. Dockerfile (I was running it on port 8444):

FROM outrigger/https-proxy:1.0
RUN sed -i -e 's/ Host .*/ Host {{ getenv "PROXY_DOMAIN" }}:8444;/' /etc/confd/templates/nginx.conf.tmpl

Then to build and run it, assuming you're using port 8444 like I did (note, host.docker.internal only works on the Mac and Windows versions of Docker; on Linux you’d probably want to use host network mode):

docker build -f Dockerfile.proxy -t proxy .
docker run --rm \
    -e UPSTREAM_DOMAIN=host.docker.internal \
    -e UPSTREAM_PORT=8080 \
    -e PROXY_DOMAIN=localhost \
    -p 8444:443 proxy

Once that’s set up, there are more steps.

1. Sign up for an account on pusher.com and get an API key.
2. Go to the Asana developer console and add a new app with OAuth authentication and a redirect URL of https://localhost:NNNN/auth where NNNN is the port number you’ll use for local connections (or you can leave off the port number if your HTTPS proxy is listening on port 443).
3. Download the Google Cloud SDK.
4. Copy config_template.php to config.php and update the API keys. I had to use an app name of “asana” on the Asana app settings. Set the redirect URL to the same URL you used in step 2.
5. Run the SDK's local dev server script and point it at app.yaml in the repo. (I had to turn off host checking due to the next step.) Something like google-cloud-sdk/bin/dev_appserver.py --enable_host_checking false /path/to/organiseasana/app.yaml

Now you can connect to https://localhost:NNNN/ and you’ll get the app home page and you can log into Asana and start copying projects.