dserve

A development server for serving branches of your docker-based web application an on-demand basis.

It can build images for any hash, run containers, stop containers that haven't been accessed in a while, proxy requests to the right container based on query params, etc.

Install

git clone [email protected]:Automattic/dserve.git
cd dserve
nvm use
yarn
yarn start

Use

You will need to modify your hosts file to include the following line:

127.0.0.1 calypso.localhost

Then you may either specify a branch or a hash to load.

branch: calypso.localhost:3000?branch={branchName}
hash: calypso.localhost:3000?hash={commitHash}

Source Code Overview

At the end of the day, dserve is node express server written in typescript. It can trigger docker image builds and deletions, start and stop containers, and a few other tricks.

Here is an example flow of what happens when requesting a never-requested-before commit sha:

User tries to access https://calypso.live?hash=hash.
dserve will query the local fs and docker daemon to determine the status of the corresponding image. It will discover that hash has never been requested before and needs to build an image for it. Therefore it will add the hash to the build queue and send the user a screen saying "starting a build for requested hash".
If the branch or hash exist, dserve will redirect the user to https://hash-$hash.calypso.live, isolating the build to a subdomain
Internally dserve checks the build queue very frequently and will initate a build within seconds. The build takes places within its own temporary directory in a place like: /tmp/dserve-calyspo-hash/repo and logs will be stored in /tmp/dserve-calypso-hash/dserve-build-log.txt.
When a user requests the branch while the build is happening, dserve will recognize that the build is in progress and show the user the build's status.
Finally when the build completes, the next time a user requests the branch they will see: "starting container, this page will refresh in a couple of seconds".

index.ts: this acts as the entry point for dserve. it sets up the server, initializes the routes, and contains the request handling for each incoming route.

middlewares.ts this file contains all of the middlewares that dserve uses.

redirectHashFromQueryStringToSubdomain: This middleware will look for a branch or hash in the query string and redirect to a corresponding subdomain matching the commit hash.
determineCommitHash: Every request to dserve needs to be associated with a commit hash or else it cannot be fulfilled. this middleware will attach a commitHash to the express request based on the subdomain.
session: Standard session middleware so that each request doesn't need to specify a hash with a query param.

api.ts: Contains all of the code that interfaces with external things like the fs, docker, or github. there are two kinds of entities that exist in this file, those that periodically update data and the other is helper functions for things that need to be done on-demand.

periodically repeating: updating the git branches to commit hash mapping, updating which docker images are available from the local docker server, stopping unused containers.

on-demand helper functions: this includes functionality for recording how recently a commitHash was accessed, a helper for proxying a request to the right container, helpers for checking the progress/state of a a commit, etc.

builder.ts: Contains all of the code for building the docker images for a specific commit hash. This includes making build queue and rate limiting dserve to N builds at a time.

logger.ts: Exports a couple key items around loggers including the application logger and a getter for configuring a specific logger per-docker build of commits.

Operations

Are you in a situation where you are suddently tasked with maintaining dserve even though you didn't write it? Once the flood of mixed feelings towards the original authors settles, it'd be a good idea to read this section. You probably want to know how to do things like, deploy new code, debug issues, and e2e test dserve locally. Here goes nothing:

deploying This GitHub repo is polled every 15 minutes. If there have been updates to the repo, then the latest sha is deployed. Thats it. Merge, and it'll be deployed. In a high severity situation where dserve is broken, you'll want to make sure you time your attempts to fix it before the next 15 minute mark.

debugging dserve has a couple helpful urls for debugging issues for times when you don't have ssh access. Note that any time you see branch=${branchName} you can subsitute hash=${sha}.

Application Log: https://calypso.live/log
List of local Docker images: https://calypso.live/localimages
Delete a build directory: add reset=1 as a query param like so https://calypso.live?branch=${branchName}&reset=1
Build Status: https://calypso.live/status?branch=${branchName}

e2e test locally

start up dserve with yarn start
try to access a branch that you've never built before by going to localhost:3000?branch=${branchName}. After a successful build you should be proxied to calypso
try to access an already built branch (by looking at the result of docker images you can find repo-tags with the right sha to specify). After a succesfful build you should be proxied to that branch's version of calypso.
you might need access to the private Docker registry: PCYsg-stw-p2

fixing errors

Docker connection error ("connect ENOENT /var/run/docker.sock"): You can easily fix this by running sudo ln -s ~/.docker/run/docker.sock /var/run/docker.sock
Error when building image: Make sure the image of the branch you are trying to build is available.

things that have broken in the past

We were running an older version of docker that had buildCache issues. disabling the build cache (as a setting in the buildImage function) until we could upgrade docker versions solved the issue
The Docker Daemon ran into problems: there was one instance where builds seemed to just hang randomly and there was no obvious cause. all builds had failed. Systems restarting the docker daemon solved the issue.
Double slash branches: there is an interesting property of git with respect to how branches get stored on the local filesystem. Each slash in a branchname actually means that it occupies a nested folder. That means if locally you have a branch named thing/thing2 then you cannot pull down a remote branch with the name thing. The reason the remote repo was capable of having branch thing/thing2 is because thing had already been deleted in its repo. The fix here is to always run a git prune when pulling down new branches which automatically deletes the appropriates local branches that no longer exist in the remote repo.

nodegit segfault when cloning repo

The current version of nodegit required by dserve, 0.23.1 segfaults when trying to clone a remote repo. This is reproducible on Debian Stable (10) using this example code from nodegit


var console = require("console");
console.log( "Here, before clone");
// Clone a given repository into the `./tmp` folder.
Git.Clone("https://github.com/nodegit/nodegit", "./tmp")
  // Look up this known commit.
  .then(function(repo) {
    // Use a known commit sha from this repository.
	console.log( "Here, in commit lookup");
    return repo.getCommit("59b20b8d5c6ff8d09518454d4dd8b7b30f095ab5");
  })
  // Look up a specific file within that commit.
  .then(function(commit) {
	console.log( "Here, in clone");
    return commit.getEntry("README.md");
  })
  // Get the blob contents from the file.
  .then(function(entry) {
    // Patch the blob to contain a reference to the entry.
    return entry.getBlob().then(function(blob) {
      blob.entry = entry;
      return blob;
    });
  })
  // Display information about the blob.
  .then(function(blob) {
    // Show the path, sha, and filesize in bytes.
    console.log(blob.entry.path() + blob.entry.sha() + blob.rawsize() + "b");

    // Show a spacer.
    console.log(Array(72).join("=") + "\n\n");

    // Show the entire file.
    console.log(String(blob));
  })
  .catch(function(err) { console.log(err); });

Because of this segfault, bootstrapping dserve is impossible (it will never be able to close the wp-calypso repo. It looks like the latest version of nodegit fixes the segfault, but there are other errors when trying to use it - it seems like there might be some API changes.

dserve-304-37 yarn[41746]: {"name":"dserve","hostname":"dserve-304-37.dca.wordpress.com","pid":41779,"level":50,"err":{"message":"Callback is required and must be a Function.","name":"Error","stack":"Error: Callback is required and must be a Function.\n    at /home/dserve/src/node_modules/nodegit-promise/lib/node-extensions.js:24:20\n    at tryCallTwo (/home/dserve/src/node_modules/nodegit-promise/lib/core.js:45:5)\n    at doResolve (/home/dserve/src/node_modules/nodegit-promise/lib/core.js:173:13)\n    at new Promise (/home/dserve/src/node_modules/nodegit-promise/lib/core.js:65:3)\n    at Repository.getReferences (/home/dserve/src/node_modules/nodegit-promise/lib/node-extensions.js:19:12)\n    at /home/dserve/src/build/api.js:221:52\n    at Generator.next (<anonymous>)\n    at fulfilled (/home/dserve/src/build/api.js:5:58)\n    at process._tickCallback (internal/process/next_tick.js:68:7)"},"repository":"Automattic/wp-calypso","msg":"Error creating branchName --> commitSha map","time":"2020-05-02T22:34:13.388Z","src":{"file":"/home/dserve/src/src/api.ts","line":326},"v":0}

Updating nodegit is probably required for #156 so trying to fix this segfault probably isn't worth it, but wanted to document it here for completeness.

automattic / dserve Goto Github PK

dserve's Introduction

dserve

Install

Use

Source Code Overview

Operations

dserve's People

Contributors

Stargazers

Watchers

Forkers

dserve's Issues

Rate Limited

Open

Recommend Projects

Recommend Topics

Recommend Org

Jobs