The readme forbids what the licence grants, and the first line points elsewhere

The first sentence of the readme recommends a different product

Before it describes anything, the readme announces that a rewrite of this project has been released, links to it, and calls it a rebuild.

The rewrite has its own name and its own domain. This project keeps its own name, its own domain, a public demo site, a user group and a five-month-old release.

So the front page is an exit. That single line reframes every maintenance question about this repository: the author is not treating it as the place to build, and a reader arriving cold is being told so before they read a feature list.

There is also an English readme beside the Chinese one in the repository root, which means the international audience was expected to arrive at a translated document rather than at the original.

For anyone deciding what to deploy, the practical order is the reverse of the readme's: look at the successor first, and read this one only if the successor does not do what you need. What follows is an account of what this one actually does.

A licence that grants commercial use and a declaration that forbids it

This is the most consequential thing in the repository, and it is a direct contradiction rather than an ambiguity.

The project is published under the Apache 2.0 licence, and there is a licence file at the root. That licence grants the right to use the work commercially.

Somewhere in the middle of the readme there is a shouted declaration, in bold with three exclamation marks, saying that without the author's permission nobody may use the project for profit or for commercial purposes, nor for illegal purposes, and that anyone who does so bears the legal responsibility.

Those two statements cannot both be operative. A licence file that grants commercial use is a permission; a readme sentence that withdraws it is a prohibition on a document that is not the licence and cannot override it. Someone relying on the readme would reasonably think the commercial use is forbidden, and someone relying on the licence would reasonably think it is allowed.

This is worth raising with the author rather than resolving unilaterally, because only the author knows which is intended. But it should not be left ambiguous in a project that advertises itself as open source, and it is the first question to ask before this goes anywhere near a product.

Three documentation links go through one URL shortener

Count the links in this readme that resolve through a shortening service and the number is three out of a small total.

The browser extension link is a short link. The help documentation link is a short link on the same domain. The user group link is a third short link on that same domain.

The destinations are not in the repository, which means the extension you install, the documentation you follow and the group you join can all change without a single commit here. For a browser extension that is the one that matters most: an extension delivered as a short link is an extension whose URL is a secret only to the person who made it.

The rest of the links are fine. The project site, the demo site and the image host are all named directly, and the image reference in the container command names the registry path plainly.

docker run -itd --name="onenav" -p 3080:80 \
    -v /data/onenav:/data/wwwroot/default/data \
    --restart always \
    helloz/onenav

So the documentation is well written and the links are fragile. That is a strange combination, because a reader who follows the short link once and it works has no way of knowing it could stop working, and no way of checking what they installed afterwards.

PHP and SQLite underneath, JavaScript in front, two interface libraries

The repository's declared primary language is JavaScript, and the project describes itself as written in PHP with SQLite. Both are true and the tree shows why.

The server side is a conventional PHP layout: a front controller at the root, a directory of classes, a directory of controllers, a directory of functions, a database directory, a configuration file with a simplified name, and a data directory. The interface side lives under a static directory and a templates directory, and the templates are the themes the readme names, one of which is where the drag-to-reorder behaviour lives.

The credit list is more informative than the language field. It names the interface library the project forked from, then two separate interface toolkits, then a lightweight database library for the PHP side. So the front end is assembled from two component libraries and the database access is a small library rather than a full object mapper.

That combination explains the single-file database: SQLite needs no server, and a bookmark set is small enough that a document store is the right shape. It also explains the deployment story, which is a tarball into a web root or one container with one mounted directory.

One front controller, a query parameter, and rewrite rules for two servers

The install instructions are four steps and the third one is unusual.

Install a PHP environment with SQLite support, unpack the source into the site root, then visit the home page and follow the prompts to set a username and password. The fourth step gives the admin address, and it is written as a plain address with a controller parameter on the front controller file.

So there is no route table and no pretty URL scheme in the readme; the entry point takes a query parameter and dispatches. That is consistent with the tree, which has a controllers directory and no configuration describing routes.

The rewrite situation is the part that will bite someone deploying this. The root carries rewrite configuration for two different web servers: one file for servers that read per-directory configuration, and one file for the other major server. The readme does not say which to use or when, and the container command does not mention either.

And there is no PHP version stated anywhere. For a project that calls for nothing but a PHP environment with SQLite support, that is a gap: the code will either work on your version or it will not, and the documentation will not tell you.

The demo site publishes its own account name and password

Under the demo heading there is a link to an official demonstration site, and beneath it an account name and a password, both in plain text.

That is a deliberate choice, and a common one: a public demo that anyone can log into is more useful to a prospective user than a screenshot. The risk is that a demo instance is a real deployment of real software, and the credentials are in a readme that gets copied around.

So the honest reading is: the demonstration instance is a sandbox, not an example of a working private deployment. Anything you would not want a stranger to read belongs on your own instance, and the project does support that, because private links are in the feature list and the rest of the data sits in a database file you control.

It is also worth noting what the demo demonstrates. The readme links the login page directly, which means the demonstration is of the authentication screen and whatever is behind it rather than of the product as a whole.

Guests and administrators get different interfaces

Two details in the feature descriptions describe behaviour that only applies once you are logged in, and neither is flagged as a limitation.

The toolbar along the bottom is hidden from visitors by default and appears only when an administrator is logged in, carrying five buttons: add a link, back to top, subscription management, system status, and the admin area itself.

And the drag-to-reorder behaviour, which is the feature the readme promotes hardest, requires a login, and within the logged-in view only triggers when you grab the link icon rather than anywhere else on the item. The readme shouts about this twice, which is how you can tell it has surprised people.

Put together with the front-end editing claim, which says all adding, editing and modifying can be done from the front end through pop-ups without entering the admin area, the picture is of a single interface whose capability depends on who is looking at it. For a bookmark page meant to be read by several people, that is a meaningful distinction, and it is not one the readme states as a choice.

Editorial conclusion

OneNav suits someone with one small server or network-attached box who wants their bookmarks in a database they control rather than in a browser sync account, and the alternate-link feature is a genuinely good fit for anyone reaching the same service from inside and outside their network. Two things to settle before you build on it. The licensing question is real and it is not going away by reading the readme again: the licence file and a shouted declaration in the readme disagree, so get that answered by the author before you use this in anything commercial. And check whether you want this project or its successor, because the readme's first sentence recommends the other one and the two have separate homes. Everything else is documented well enough to install in a quarter of an hour.

Frequently asked questions

Official sources

1. helloxz/onenav on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases