Document deployment expectations

[PeterJCLaw]

Not sure if this should be here or against srcomp-cli; nor where the docs will go (either the README here, srcomp-cli's docs or part of the SRComp wiki).

While there is some mention in various places of what a deployed compbox looks like, it's missing some key details.

The main thing I'm aware of biting people is that the name in the deployments file needs to point directly to the machine for both HTTP API access and SSH access; this is alluded to but not made clear. As part of this we should suggest using local (~/.ssh/config) aliases can help if there are reasons to break one of these assumptions.

As part of this it may also make sense to document why the act of doing a deploy (i.e: updating the deployed compstate) works the way it does -- namely by push, not pull.

I suspect there may be other things too.

[PeterJCLaw]

@Alexbruvv I think you recently tried to deploy SRComp via cloudflare? Were there any other things you hit while doing that which could be better documented (or the system improved to have better feedback or just remove the gotchas entirely)?

[Alexbruvv]

I have two deployments that use CloudFlare at the moment, neither of which have been particularly problematic. The first is just a standard deployment in a DigitalOcean droplet with an A record in CloudFlare; the only problem I found here was deploying compstate changes didn't work if the DNS record was proxied through CloudFlare (which I assume is because CloudFlare doesn't proxy SSH traffic?).

The second is through CloudFlare tunnels, whereby the deployment is on an internal network, and we use the tunnel largely to expose the API externally. Again no issues with this - other than, as expected, compstate deployments have to be done on the internal network.

The only thing I struggled with when deploying was figuring out how to 'mount' the right compstate repo. My solution was to SSH in, log in to Git and replace the dummy repo with the target. It's entirely possible I missed some documentation on this somewhere though.

[PeterJCLaw]

Thanks for that context :)

I have two deployments that use CloudFlare at the moment, neither of which have been particularly problematic. The first is just a standard deployment in a DigitalOcean droplet with an A record in CloudFlare; the only problem I found here was deploying compstate changes didn't work if the DNS record was proxied through CloudFlare (which I assume is because CloudFlare doesn't proxy SSH traffic?).

That's odd. If you've got an A record pointing directly at the droplet, I'm not sure what CloudFlare could be doing which would break that. I'm also not really sure what you mean by the DNS record being proxied.

Do you mean that you previously had the droplet being (HTTP) proxied by CloudFlare (i.e: the DNS pointing at CloudFlare, which then proxied the droplet)? If so, yeah you'd need to configure some way for the name to resolve properly for SSH too. Having the proxy pass that through could work, though a local ~/.ssh/config which pointed the FQDN somewhere would work too. The latter is probably the more expected route -- ~/.ssh/config working here is expected/supported (though may not be documented).

The only thing I struggled with when deploying was figuring out how to 'mount' the right compstate repo. My solution was to SSH in, log in to Git and replace the dummy repo with the target. It's entirely possible I missed some documentation on this somewhere though.

Ah, yeah. That's not very clear at the moment. The expectation is that the first deploy will just deploy over the top of the dummy compstate. There shouldn't be any need to manually adjust the compbox once it's set up.

I wonder if there's a way to make that more obvious 🤔. The current setup is somewhat dev-friendly, and makes it easy to validate a compbox is set up correctly without needing the intended compstate to be ready, though I appreciate it's not obvious that that's expected.