Koa

To run apps built with the Koa web framework using Unit:

Install Unit with the unit-dev/unit-devel package. Next, install Unit’s unit-http package. Run the following command as root:
console
# npm install -g --unsafe-perm unit-http
```
# npm install -g --unsafe-perm unit-http
```

Create your app directory, install Koa, and link unit-http:

$ mkdir -p /path/to/app/ #Path to the application directory; use a real path in your configuration

$ cd /path/to/app/ # Path to the application directory; use a real path in your configuration

$ npm install koa

Run the following command as root:

# npm link unit-http

Let’s try a version of the tutorial app, saving it as /path/to/app/app.js:

const Koa = require('koa');
const app = new Koa();

// logger

app.use(async (ctx, next) => {
  await next();
  const rt = ctx.response.get('X-Response-Time');
  console.log(`${ctx.method} ${ctx.url} - ${rt}`);
});

// x-response-time

app.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
});

// response

app.use(async ctx => {
  ctx.body = 'Hello, Koa on Unit!';
});

app.listen();

The file should be made executable so the application can run on Unit:

$ chmod +x app.js # Application file; use a real path in your configuration

Change ownership:

Run the following command (as root) so Unit can access the application directory (If the application uses several directories, run the command for each one):
console
# chown -R unit:unit /path/to/app/ # User and group that Unit's router runs as by default
```
# chown -R unit:unit /path/to/app/  # User and group that Unit's router runs as by default
   
```
The unit:unit user-group pair is available only with official packages , Docker images, and some third-party repos. Otherwise, account names may differ; run the ps aux | grep unitd command to be sure.

For further details, including permissions, see the security checklist.

Next, prepare the Koa configuration for Unit:

{
   "listeners": {
      "*:80": {
         "pass": "applications/koa"
      }
   },
   "applications": {
      "koa": {
         "type": "external",
         "working_directory": "/path/to/app/",
         "working_directory_comment": "Needed to use the installed NPM modules; use a real path in your configuration",
         "executable": "/usr/bin/env",
         "executable_comment": "The external app type allows to run arbitrary executables, provided they establish communication with Unit",
         "arguments": [
         "node",
         "--loader",
         "unit-http/loader.mjs",
         "--require",
         "unit-http/loader",
         "app.js"
         ],
         "arguments_comment": "The env executable runs Node.js, supplying Unit's loader module and your app code as arguments",
         "app_js_comment": "Basename of the application file; be sure to make it executable"
      }
   }
}

Upload the updated configuration.

Assuming the JSON above was added to config.json. Run the following command as root:

# curl -X PUT --data-binary @config.json --unix-socket \
      /path/to/control.unit.sock \  # Path to Unit's control socket in your installation
      http://localhost/config/      # Path to the config section in Unit's control API
   

The control socket path may vary; run unitd -h or see Startup and shutdown for details.

After a successful update, your app should be available on the listener’s IP address and port:

$ curl http://localhost -v

      *   Trying 127.0.0.1:80...
      * TCP_NODELAY set
      * Connected to localhost (127.0.0.1) port 80 (#0)
      > GET / HTTP/1.1
      > Host: localhost
      > User-Agent: curl/7.68.0
      > Accept: */*
      >
      * Mark bundle as not supporting multiuse
      < HTTP/1.1 200 OK
      < Content-Type: text/plain; charset=utf-8
      < Content-Length: 11
      < X-Response-Time: 0ms
      < Server: Unit/1.34.1

      Hello, Koa on Unit!

Last modified February 6, 2025