Previously, documentation for new releases of CASE/UCO would have to be manually built using gendocs/ontodocs, in order to deploy documentation via the project websites (CASE/UCO). With this repository, building the documentation and deploying it on the web will be a more automated process, and allow for local documentation to be built for necessary cases.
For those interested in local documentation, the routing infrastructure currently assumes HTTP service (whether ontology documentation or machine-consummable RDF formats) will be done using HTTPS only.
The intended audience for this section is documentation maintainers.
The documentation generation must be carried out on a case-sensitive file system. (macOS's default file system deployment is case-insensitive.)
Do not commit changes under the /case directory on a case-insensitive file system. Conflicts due to upper-vs.-lower casing will create erroneous concept files. Be aware that changes will be present on a fresh git clone in a case-insensitive file system.
When a new ontology release is created, follow these steps:
- Update the ontology-tracking submodule pointer in this repository to point at the new release's commit.
- Run
make clean. - Run
make. (make -jwill work.) - Run
git add case documentation. This will pick up all file deletions and new file creations. - Run
git addfor the other refreshed text files in${top_srcdir}. - Commit the changes.
- Push to GitHub.
For the deployment of the documentation, we assume this repository is cloned to a Linux server, becoming the directory /srv/http/ontology.caseontology.org/. The nginx configuration file and casedocs systemctl service file are pathed to this directory by default.
Note that this service is only tested under the operational assumption that the documentation will be served over HTTPS. All routing initiated over HTTP will be upgraded to HTTPS. Please plan TLS certificates accordingly.
To deploy, the system will need to have Nginx installed and this repository cloned on it. We will use a simple flask router and a series of version-specific mapping files to route traffic to the proper documentation pages. This CONTRIBUTE.md page will outline installing Nginx and utilizing the Makefile to test the setup. All commands will assume the deployment system is a Debian-based system (such as Ubuntu).
First, update the package repositories and update the system:
$ sudo apt-get update
$ sudo apt-get -y upgradeThen, install Nginx on the server, and python3-venv if the server's operating system is Ubuntu:
$ sudo apt-get install nginx python3-venvCreate a directory where the CASE autodocs repository will live, and a dedicated system user:
$ sudo mkdir -p /srv/http/ontology.caseontology.org
$ sudo useradd --create-home --shell /usr/sbin/nologin --system casedocs
$ sudo chown casedocs:casedocs /srv/http/ontology.caseontology.org(--create-home is suggested for shell auditing purposes, and would create /home/casedocs if passed.)
Use the new system user to clone this repository on the machine, you will need to initalize a repository in the service directory, to be able to pull to the non-empty target:
$ sudo su casedocs -s /bin/bash
$ cd /srv/http/ontology.caseontology.org
$ git init
$ git remote add origin https://github.com/casework/ontology.caseontology.org.git
$ git fetch
$ git checkout mainChange directories to the router/ directory, and build the flask router:
$ cd router/
$ make clean
$ make
$ # (Work as the 'casedocs' user is concluded.)
$ exitLink the casedocs.service file so that systemctl can use it, reload, and enable the service. Note: If this deployment expects to modify the service file, e.g. to change the User line, it should be copied (cp) instead of soft-linked as documented.
$ cd /etc/systemd/system
$ sudo ln -s /srv/http/ontology.caseontology.org/router/casedocs.service
$ sudo systemctl daemon-reload
$ sudo systemctl enable casedocs.service
$ # Start the flask router and check the status of it
$ sudo service casedocs start
$ sudo service casedocs statusAssuming that the casedocs service starts successfully, you can proceed to copy the nginx configuration file to the sites-enabled directory and remove the default file. Note: Again, if this deployment expects to adapt the nginx configuration file, e.g. to change the server name, it should be copied instead of soft-linked as documented.
$ cd /etc/nginx/sites-enabled
$ sudo ln -s /srv/http/ontology.caseontology.org/router/case.nginx.conf
$ sudo rm default
$ sudo service nginx configtest
$ sudo service nginx restartYou should now be able to navigate to the IP address of your system and see the documentation live:
$ # (to get the IP information)
$ ip a sTo modify the nginx configuration file and add a hostname, change the server_name line as follows:
server {
listen 80;
- server_name ontology.caseontology.org;
+ server_name mywebsite.com;
location /documentation {
root /srv/http/ontology.caseontology.org;
try_files $uri $uri/ /index.html =404;
}
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}To refresh served files (i.e. RDF-XML, Turtle, HTML and HTML-supporting files), these are the only steps that need to be run:
$ sudo su casedocs -s /bin/bash
$ cd /srv/http/ontology.caseontology.org
$ git pull
$ exitIf there were no revisions under router/, the update process is complete.
If there are revisions to router/case.nginx.conf or router/casedocs.service, and those files are soft-linked under /etc, these commands will restart and reload web service. If the files were not soft-linked, review the diffs and apply the same changes to the copied files under /etc.
$ sudo systemctl daemon-reload
$ sudo service casedocs restart
$ sudo service casedocs status
$ sudo service nginx configtest
$ sudo service nginx restart
$ sudo service nginx statusIf you are running the deployment on a system that does not access the internet, or you wish to only provide the documentation locally, you may want to add an entry to your hosts file.
$ sudo vi /etc/hostsTo test the deployment, run the Makefile to ensure expected URL behaviors and content types. Unparameterized, this call will confirm files retrieved from localhost content-match expected files in the source tree:
$ make check-serviceIf you have set the server_name on nginx as anything besides localhost, you will want to supply this prefix with the HOST_PREFIX parameter. For example, to test the production service, run:
$ make HOST_PREFIX=https://ontology.caseontology.org check-serviceAs another example, if you have a local deployment at https://documentation.intranet.example.org/, run:
$ make HOST_PREFIX=https://documentation.intranet.example.org check-serviceThere are a variety of errors that you can face, but we are going to address the most common ones.
403 - For 403 errors, check to ensure that the permissions are properly set on the folder and files. For this, we will use the example directory /srv/http/ontology.caseontology.org:
$ sudo find /srv/http/ontology.caseontology.org -type d -exec chmod 775 {} \;
$ sudo find /srv/http/ontology.caseontology.org -type f -exec chmod 664 {} \;
$ sudo chown -R casedocs:casedocs /srv/http/ontology.caseontology.org404 - For 404 errors, is commonly a symptom of the pathing between nginx and the flask router being incorrect:
- Ensure that the paths defined in the systemctl file (
/etc/systemd/system) are correctly pointing to the router - Check the nginx configuration file (
/etc/nginx/sites-enabled/) to ensure that the pathing to the documentation is correct - Ensure that
defaultconfig for nginx is deleted (no longer in/etc/nginx/sites-enabled/*) - Check that the requested file actually exists!
tail -f /var/log/nginx/error.log
500 - For any 500 errors, the server may be mis-configured, you can check the following areas to see if there is relevant outputs. This is commonly due to a typo (perhaps an updated path?) in one of the sites which are enabled.
$ sudo tail -f /var/log/nginx/error.log
$ journalctl