Sequiturs

What is Sequiturs?

See https://ianhinsdale.com/post/introducing-sequiturs/ and https://ianhinsdale.com/post/voting/.

Application

"Application" refers to the Sequiturs web application (backend: web server + REST API (currently colocated in the same node server); frontend: React single-page app) and the background worker.

These instructions are relative to the /application directory.

1. Running locally

1. Within sysadmin/local_dev/run:
   1. In one terminal window:

      sh install.sh
      sh configure.sh
      sh run.sh
      

      • This installs major application dependencies, configures your environment, and runs the Postgres, Redis, and Nginx services.
2. Within src:
   1. In another terminal window:

      gulp compileDevel
      

      • This compiles static assets served by the node server. It watches /public for changes and recompiles continually.
      • Note that changes to /templates are not watched, so gulp compileDevel will need to be re-run and the node server restarted for changes to those files to be reflected.
   2. In another terminal window, after the previous step is complete:

      npm run develop-app
      

      • The develop-app npm script runs the main application web server. For local development, we run this server via nodemon, which watches for file changes and restarts the server.
   3. In another terminal window:

      npm run develop-worker
      

      • This runs the background job worker, via nodemon (so the worker will restart on file changes).
3. In another terminal window, from within sysadmin/local_dev/run:

   sh populate.sh
   

   • This populates the local Postgres db with helpful fixture data for developing locally.
4. Visit https://localhost in your browser. You will receive a security warning due to the server's self-signed SSL certificate. Ignore the warning and proceed.
5. To run the prompt-intelligence microservice, which is consumed when accepting/rejecting a prompt suggestion, see that repo's README.

Embed app

The embed app is the version of the Sequiturs web app that is intended for being embedded in a web page on any host, via an iframe.

When developing the embed app, you can see how your local changes look when embedded, by looking at the special embed-app test host which we've set up for this purpose. Code related to the embed-app test host lives in application/src/embed_app_test_host and application/sysadmin/production/roles/embed_app_test_host_express.

Here's the procedure for getting yourself set up to develop locally:

1. Run application/sysadmin/local_dev/populate.sh to populate your local db with the necessary config values that will make your local server work with the embed-app test host.
2. Connect to the VPN.
3. Go to http://embedsequiturstest.com/blog/iframe-src-localhost/public-channel/wants-to-use-with-embed-app/:foo where :foo is any random string you want.
   • There are actually a number of different routes on that host you can work with, corresponding to different ways the embed app might be used out in the wild. You can see what these routes are in application/src/embed_app_test_host/routes/blog.js.
   • That host is also part of our staging environment infrastructure, as it serves routes that are used in our staging environment tests.
4. That page contains an iframe which points to the embed-app routes on your local server. You're in business!

Troubleshooting

• You can stop your locally running pg, redis, and nginx services with sh run.sh stop.
• If you get the nginx error

nginx: [emerg] bind() to 0.0.0.0:80 failed (48: Address already in use)
nginx: [emerg] bind() to 0.0.0.0:443 failed (48: Address already in use)

use sudo nginx -s stop and then try run.sh again.

2. Tests

To run tests, first run the application locally. Then, within src, run npm run test-local. This will run all tests that are appropriate for running against the local application: unit and integration tests, but not production smoke tests. Integration tests and unit tests are broken into separate npm packages, so if you want to run one of these suites individually, you can cd into the relevant sub-directory within /test, and run npm test there.

Publishing changes to the blog

1. Run gulp compileBlog, inside /src.
2. Review the changes and commit.
3. Follow normal deploy process.

Publishing changes to the open-source docs

1. Run gulp compileOSSDocs, inside /src..
2. Review the changes and commit.
3. Follow normal deploy process.