Maintenance¶

Configuration updates using ansible¶

The Installation section explains how to create an ansible playbook and use it for the initial installation of the Data Library software. We also recommend that you use continue using ansible to manage configuration changes and software updates over time.

To make a configuration change,

In your dlconfig repository, edit the relevant variable in playbook.yaml. Advanced ansible users can also add custom tasks to the playbook.

Run the playbook in “check mode” to verify that ansible will make the change you intended:

  ansible-playbook \
    --check \
    --diff \
    --ask-become-pass \
    -i inventory.cfg \
    -e @../secrets.yaml \
    playbook.yaml

After verifying the diff, run the playbook without --check --diff to apply the change.

  ansible-playbook \
    --ask-become-pass \
    -i inventory.cfg \
    -e @../secrets.yaml \
    playbook.yaml

Commit and push your changes to your git host.

To update to a new version of the Data Library software, first consult the release notes for any backwards-compatibility warnings and manual migration steps. Then use ansible-galaxy to update the ansible_collections directory of your dlconfig repository:

 ansible-galaxy collection install iridl.iridl:==x.y.z

where x.y.z is the new Data Library version number. Remember to commit and push your changes.

Adding user accounts¶

As described in User groups, users with accounts on the Data Library server can be divided in two groups: administrators and authors.

Administrator accounts should be created “by hand”, i.e. outside of ansible’s control. Remember to add administrators to the wheel group so they will have sudo privileges.

Author accounts should be created by adding the user to the datag_users list in playbook.yaml and running ansible (see Configuration updates using ansible). Ansible will create the user account, add the new user to the datag group, and create a personal data catalog directory (see Important file and directory paths) for the user. Ansible does not set the user’s password, so you should do that by hand after running the playbook. Remember to commit and push your playbook changes.

Debugging tips¶

To see what services are running under docker, use sudo docker ps.
To start and stop services, cd to /usr/local/datalib and then use docker-compose, e.g.
```
  cd /usr/local/datalib
  sudo docker-compose up -d maproom
```
Most services output logs to stdout, which is captured by the docker daemon and routed to journald. You can read the logs by using journalctl, e.g.
```
  sudo journalctl CONTAINER_NAME=datalib_maproom_1 --since='1 hour ago'
```
squid produces two separate logs: the error log and the access log. The latter contains a line for each request served. The error log is piped to journalctl, while the access log is written to a docker volume. To read the access log, use docker exec to run a command in the squid container, e.g.
```
  sudo docker exec -it datalib_squid_1 tail -n 100 /var/log/squid/access.log
```
If an embedded image in a maproom is broken/empty, copy the image URL to a new browser window and remove the .gif at the end. Sometimes this will get you an informative error message instead of just an empty response.
If there’s an error message about a specific file or database table, look into that as described below. If no specific file or table is mentioned, identify the datasets that are used in the query, and read the catalog entries (dlentries) for those datasets to identify the files and/or tables that they use.
To check on a database table, exec into the postgres container and use psql. If the table doesn’t exist, either run the sql script that creates it, or add it to the sql scripts if it’s missing. If the table exists, check that the readonlyaccess role has select permission for it. (Our install process is supposed to grant that permission, but in rehearsing the installation we have sometimes needed to grant it by hand.)