Missed 'servers' in 'full example' section about unit-docs

Thanks for noticing this and shame on me; the issue is fixed now.

This object is subject to possible change in the future, so we'll keep it this way.

[VBart]

Hi. @VBart @artemkonev
I put a demo online only for preview.
http://120.24.208.31:9528

Looks good!

There are some questions I faced.

* home page
  I'm still not sure what information is good to put here.

Probably just an overview.

I'm not sure that multiple screen/pages are needed right now. Everything can be showed and edited on just one page without switching (which can distract).

* access log
  Where to put it? I want to put it into `settings`, but it has an individual section in Unit configuration.

You shouldn't stick to JSON structure of the API. It's just an internal detail. UI can have completely different organisation, if it suits better.

* certifications

export function add(data) {
  var name = data['name']

  var value = `-----BEGIN PRIVATE KEY-----
${data['private_key']}
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
${data['certificate']}
-----END CERTIFICATE-----`

  return request({
    url: '/certificates/' + name,
    method: 'put',
    data: value
  })
}

I'm not sure if it's right to calculate the value from html form.

There are also problems with copy'n'paste from editors. Sometimes it may corrupt the certificate somehow. I'd suggest to implement ability for file uploading and drag'n'drop as well.

* nginx config
  Now, it seems nginx is required to do the `CORS` and `login/authorization`.

server {
    listen  8000;

    error_page 451 = @cors;
    if ($request_method = OPTIONS) {
        return 451;
    }

    location @cors {
        internal;
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Max-Age 3600;
        add_header Access-Control-Allow-Methods 'GET, PUT, POST, DELETE, OPTIONS';
        add_header Access-Control-Allow-Headers '*';
        return 204;
    }

    add_header Access-Control-Allow-Origin * always;
    add_header Access-Control-Expose-Headers 'Date';

    location /user/login {
        return 200 '{"token": "xxx"}';
    }

    location /user/info {
        return 200 '{"username": "admin"}';
    }

    location /user/logout {
        return 200;
    }

    location / {
        proxy_pass  http://127.0.0.1:8080;
        proxy_intercept_errors on;
        if ($request_method = GET) {
          error_page 404 = @empty;
        }
    }

    location @empty {
        internal;
        return 204;
    }
}

a. CORS
It would be helpful if UNIT support CORS itself.

That's because the UI and Unit API are served from different hosts. Do you think that will be a common case?

b. login/autorization
I think authorization is necessary. I want to use njs to implement it. It depends on njs jwt implementation.

I agree. What authorization methods do you think Unit should support out of the box?

c. 404
Please take a look again. In routes edit, we need to get all the pass options such as upstreams.
If there is not config/upstream, the request will get 404 from the server-side.
In JS request, it will trigger an error (I didn't find a better way).

Is it a problem to handle this error?

I think "requesting every bit" for the "pass" option - isn't a good way to handle it. Also this doesn't work with PHP targets.

And you also lose atomicity. Parts of config may be changed by other software or users between your requests.

It's better to request the full JSON from /config/ and then parse it and extract different parts.

So I added an error page in nginx configuration.
Do you think it makes sense that return 200 and null if the method is GET and value is not found?
For example, If /config/upstreams don't exist.
GET /config/upstreams => 200
GET /config/upstreams/a => 404
(I know it looks good now in Unit).

That violates the REST principles that we try to stick.

* Open-source
  There are two parts: source and dist. I only use the `README` and `src` directory.

babel.config.js  jest.config.js  mock          package-lock.json  README.md     tests
build            jsconfig.json   node_modules  postcss.config.js  README-zh.md  vue.config.js
dist             LICENSE         package.json  public             src

It's easy to use dist, just change the API address.
I'm thinking about how to organize the project including nginx configuration.

Note that this server does not have any application environment, I tested it in my local server.
(GO/php/perl/ruby passed)

This is based on vuejs. I'm a bit new to web and I did it only by myself.
Highly welcome to get suggestions and help in the future.

The core part is the JS. Everything else is just a way how it can be served and it would be nice, if nginx will be not needed at all in the future. And it's not needed right now if you're using web UI locally for development for example.

Also one more note, unrelated to the above. It seems currently it's not possible to add listeners and routes, or routes and apps or just multiple routes at the same time. Each time when adding something, you have to click "Submit" and apply changes, which can result in inconsistent state of the configuration. You have to collect all the changes made by user until he decide to apply them.

[hongzhidao]

@artemkonev

settings/http/websocket is also missed in the document. For example.

{
    "settings": {
        "http": {
            "header_read_timeout": 2,
            "idle_timeout": 0,
            "websocket": {
                "read_timeout": 3,
                "keepalive_interval": 0,
                "max_frame_size": 4
            },

Hi, @hongzhidao ,
Initially, this was done on purpose, but I'll check whether this omission should stay as it is.

[hongzhidao]

@artemkonev
It would be great to have a section to describe how to upgrade, including software such as Unit 1.8 to Unit.19,
and what should users do after changing Go/Python/PHP code?

Thanks, @hongzhidao, I'll consider adding this to my roadmap for the future.

[hongzhidao]

Hi, @artemkonev @VBart

1. What about adding lang type in each language sample? For example
   <%= "Hello, Unit Java!" %>
2. Some options are inconsistent in docs, tests and source code.
   unit_jars exists in tests and source code, but not in docs.
   reschedule_timeout seems unused.
   shm only exists in source code.

BTW, does the official UNIT plan to support the dashboard?
I'm working on this recently, and it's almost finished.
It would be great to have suggestions from you.

[VBart]

1. Good idea..

2. unit_jars was introduced just for our tests. Some options aren't documented as we aren't sure that it's a good idea to allow users to configure them or the future of these options is uncertain, but we have them in the code just in case. The reschedule_timeout is one example of such option. It was only used for previous IPC implementation (before 1.19.0) and now lost any sense. It should be removed from the code, though. Note, that having excessive configuration can be even greater evil then not having it at all. By keeping some questionable options off the documentation, we avoid using them by most users.

Dashboard is a good idea and Unit control API suits well here. However there are no plans to create one right now. Are you going to open source your dashboard? It would be nice to see, and we can mention it in the docs or in a blog post.

1. Noted.

[hongzhidao]

@VBart

Are you going to open source your dashboard? It would be nice to see, and we can mention it in the docs or in a blog post.

Yes. Soon will be released. Thanks for your suggestion.

[hongzhidao]

Hi. @VBart @artemkonev
I put a demo online only for preview.
http://120.24.208.31:9528

There are some questions I faced.

• home page
  I'm still not sure what information is good to put here.
• access log
  Where to put it? I want to put it into settings, but it has an individual section in Unit configuration.
• certifications

export function add(data) {
  var name = data['name']

  var value = `-----BEGIN PRIVATE KEY-----
${data['private_key']}
-----END PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
${data['certificate']}
-----END CERTIFICATE-----`

  return request({
    url: '/certificates/' + name,
    method: 'put',
    data: value
  })
}

I'm not sure if it's right to calculate the value from html form.

• nginx config
  Now, it seems nginx is required to do the CORS and login/authorization.

server {
    listen  8000;

    error_page 451 = @cors;
    if ($request_method = OPTIONS) {
        return 451;
    }

    location @cors {
        internal;
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Max-Age 3600;
        add_header Access-Control-Allow-Methods 'GET, PUT, POST, DELETE, OPTIONS';
        add_header Access-Control-Allow-Headers '*';
        return 204;
    }

    add_header Access-Control-Allow-Origin * always;
    add_header Access-Control-Expose-Headers 'Date';

    location /user/login {
        return 200 '{"token": "xxx"}';
    }

    location /user/info {
        return 200 '{"username": "admin"}';
    }

    location /user/logout {
        return 200;
    }

    location / {
        proxy_pass  http://127.0.0.1:8080;
        proxy_intercept_errors on;
        if ($request_method = GET) {
          error_page 404 = @empty;
        }
    }

    location @empty {
        internal;
        return 204;
    }
}

a. CORS
It would be helpful if UNIT support CORS itself.
b. login/autorization
I think authorization is necessary. I want to use njs to implement it. It depends on njs jwt implementation.
c. 404
Please take a look again. In routes edit, we need to get all the pass options such as upstreams.
If there is not config/upstream, the request will get 404 from the server-side.
In JS request, it will trigger an error (I didn't find a better way).
So I added an error page in nginx configuration.
Do you think it makes sense that return 200 and null if the method is GET and value is not found?
For example, If /config/upstreams don't exist.
GET /config/upstreams => 200
GET /config/upstreams/a => 404
(I know it looks good now in Unit).

• Open-source
  There are two parts: source and dist. I only use the README and src directory.

babel.config.js  jest.config.js  mock          package-lock.json  README.md     tests
build            jsconfig.json   node_modules  postcss.config.js  README-zh.md  vue.config.js
dist             LICENSE         package.json  public             src

It's easy to use dist, just change the API address.
I'm thinking about how to organize the project including nginx configuration.

Note that this server does not have any application environment, I tested it in my local server.
(GO/php/perl/ruby passed)

This is based on vuejs. I'm a bit new to web and I did it only by myself.
Highly welcome to get suggestions and help in the future.

[hongzhidao]

I'm not sure that multiple screen/pages are needed right now. Everything can be showed and edited on just one page without switching (which can distract).

This inspired me. On the client-side, there is only one JS object stored.

I'd suggest to implement ability for file uploading and drag'n'drop as well.

It's better to support both ways.

That's because the UI and Unit API are served from different hosts. Do you think that will be a common case?

I'm not sure. I prefer to keep Unit API unchanged and put CORS, etc into NGINX in the short time.

I agree. What authorization methods do you think Unit should support out of the box?

I guess in real-world this dash will be deployed in the local network (I mean the login is not required) and the way of jwt auth is a good choice for login.

And it's not needed right now if you're using web UI locally for development for example.

OK. Please take a look at the first try. hongzhidao/nginx-unit-dashboard.
All are done. Welcome to test.
I'm thinking if the sources(views,apis) are useful to put in the project. The dist directory is built by npm with these sources. Welcome to your suggestions.

You have to collect all the changes made by user until he decide to apply them.

The following are my thoughts.

1. The dash is a handy tool to help people manage the Unit's configuration besides cli. It totally follows the instructions described in Unit docs. So I organize the menus the form fields corresponding to the docs.
2. I think which way should be supported, the complete submit or submit after form editing. Both these ways are needed in real-world compared to NGINX used in the company. For the way of complete submit at the same, actually, the versions is needed. People can create a draft version and deploy it, even do the rollback. So currently I prefer to only support the way of submit after editing.
3. I want to keep the dashboard corresponding to the Unit's document. http://120.24.208.31:9528 is updated.

Other.

1. It seems metrics can be put into the dash if it's introduced in Unit.
2. I added upstream type. Are other polices will be supported in the future, such as consistent hash?
3. Some options like new_privs, automount not described on the docs are not shown on the dash. I think it's better to only show the options described on the docs.