diff --git a/README.md b/README.md index 9531315..52298de 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,92 @@ # LibriVox-ansible These are the Ansible playbooks used to deploy -[LibriVox](https://librivox.org/). They are designed for and tested on an -Ubuntu Jammy target with networking and SSH already configured. The playbooks -do everything else. +[LibriVox](https://librivox.org/). ## Scrubbed catalog database A scrubbed (all personal information removed) catalog database snapshot is -[available](resources/librivox_catalog_scrubbed.sql.bz2). It can -be used as part of a local LibriVox development environment (see next section) -or on its own by anyone interested. +[available](roles/db_import/files/librivox_catalog_scrubbed.sql.bz2). It can +be used as part of a local development environment (see next section) or on its +own by anyone interested. -## Local development environments +## Local development environment -These playbooks were written with production and staging deployments in mind. -That being said, some considerations were given towards using them for -deploying local development versions of LibriVox. That use case isn't fully -supported (yet?), but with some elbow grease it can be done. A guide is -[available](doc/localdev.md). +These playbooks can set up a local development environment, hereafter called +"localdev". Localdev is a limited version of LibriVox with only the catalog +operational. The forum, wiki, and WordPress blog are installed, but their +databases are empty. The catalog database is the scrubbed one, so while all the +book information is there, the user information is anonymized. + +### Prerequisites + +* A Ubuntu Jammy 22.04 environment, the target. +* An environment to run these Ansible playbooks in, the executor. +* SSH access to the target from the executor. +* Sudo access in the target. +* Ansible installed on the executor. + +Setting the target and the executor is purposefully left out of scope of this +guide. The most likely scenario is the executor being a laptop or PC, with the +target as a VM or container (LXC works well) on the executor. Other +combinations are possible, including the target and the executor being the same +system, as long as the prerequisites are met. + +### Deployment + +On the executor, clone this repository: + +``` +$ git clone https://github.com/librivox/librivox-ansible +$ cd librivox-ansible +``` + +Edit `inventory.yaml` and replace 192.168.122.12 with the IP address of the target system: + +``` +localdev: + hosts: + 192.168.122.12: +``` + +Run the localdev playbook: + +``` +$ ansible-playbook -i inventory.yaml localdev.yaml --ask-become-pass +``` + +Ansible prompts for the BECOME password. Enter the sudo password. + +### Access + +To access the localdev target from a different environment (for example, from +the executor), the following line needs to be present in that environment's +hosts file (on most Unices including Mac, the hosts file is `/etc/hosts`, on +Windows it's `C:\Windows\System32\drivers\etc\hosts`): + +``` +192.168.122.12 librivox.org +``` + +Replace `192.168.122.12` with the IP address of the Ansible target. + +### Caveats/disclaimers + +* Localdev uses a self-signed TLS certificate. The scary TLS warning is + expected, and needs to be accepted. +* The forum, wiki, and blog have empty databases, and thus do not work. +* Works: + * [Search](https://librivox.org/search) + * Individual books (ex: + https://librivox.org/dust-of-the-desert-by-robert-welles-ritchie/) + * [The workflow](https://librivox.org/workflow) +* Does not work: + * [The home page](https://librivox.org) redirects to the WordPress + initialization page. + * [The forum](https://forum.librivox.org/) + * [The wiki](https://wiki.librivox.org/) + +### Development + +The librivox-catalog repository is cloned to +`/librivox/www/librivox.org/catalog` diff --git a/doc/localdev.md b/doc/localdev.md deleted file mode 100644 index 7540b00..0000000 --- a/doc/localdev.md +++ /dev/null @@ -1,149 +0,0 @@ -# Installing LibriVox locally - -## Overview - -This cookbook describes how to set up a local LibriVox installation -inside a VirtualBox VM using the `librivox-ansible` GitHub project. - -Some parts of the LibriVox installation (files, databases) are made -accessible to the host system, to allow the development to happen -on the host machine. - -The installation uses the original host names, which will be overridden -in the `hosts` file. This is because the whole setup currently has these -host names hardcoded. - -Note: This guide is not meant to be perfect or finished, but helpful. -It tries to avoid many of the possible obstacles. -If you want to improve this document, just edit it and send a pullup -request. - -## VirtualBox - -Download and install VirtualBox 5.2.8. - -## Ubuntu - -* Download Ubuntu Xenial, server edition -* Create a new VM inside VirtualBox: - * 1 GB RAM - * 50 GB dynamic disk space - * Bridged networking -* Install Ubuntu in that VM - * Select all feature sets - -## Easy root privileges - -The LibriVox playbook runs most of the tasks as root user. -To make this easy, give your user complete root permissions without password. -After all, this is just in a virtual machine in a private environment, -so convenience is more important than security. - - echo "$USER ALL=(ALL:ALL) NOPASSWD: ALL" > "/etc/sudoers.d/$USER" - -## Disable IPv6 - -From inside the VM, run: - - ping6 www.google.com - -If that works, skip the rest of this section. -But if you get a network timeout, disable IPv6 networking: - - echo 'net.ipv6.conf.all.disable_ipv6 = 1' > /etc/sysctl.d/01-disable-ipv6.conf - reboot - -## Additional packages - - sudo su - - apt update - apt upgrade - apt install git gcc make perl python - exit - -## Ansible - -LibriVox requires Ansible >= 2.4, while Ubuntu comes with 2.0. -Therefore, install Ansible from source. - - mkdir git - cd git - git clone https://github.com/ansible/ansible - cd ansible - python setup.py build - python setup.py install --user - ansible --version - -## Adjust LibriVox playbook for local development - - cd git - git clone https://github.com/librivox/librivox-ansible - cd librivox-ansible - - ipaddr=$(ifconfig | perl -ne 'printf("%s\n", $1) if /^\s+inet addr:\s*(\S+)/ && $1 ne "127.0.0.1"') - printf '[server]\n%s\n' "$ipaddr" > hosts/localdev/hosts - -Do not let Git overwrite the local changes when updating: - - perl -i -pe ' - s/force: yes/force: no/ if $module eq "git"; - $module = $1 if /^ (\w+)/; - ' */*/tasks/main.yml - -## Let the playbook run - - ansible deploy.yml -i hosts/localdev/hosts - -## Access LibriVox from the host system - -In `/etc/hosts` or `C:\Windows\System32\drivers\etc\hosts`, add: - - 192.168.178.87 librivox.org - 192.168.178.87 dev.librivox.org - 192.168.178.87 forum.librivox.org - 192.168.178.87 wiki.librivox.org - 192.168.178.87 www.librivox.org - -Replace `192.168.178.87` with the IP of the LibriVox VM (see `ipaddr` above). - -### Set up developer account for MySQL - -To browse the LibriVox databases from the IDE, add a MySQL user: - - sudo mysql - grant all privileges on *.* to `librivox`@`%` identified by 'librivox'; - -### Initialize the catalog database - - mysql -ulibrivox -plibrivox -e 'CREATE DATABASE librivox_catalog' - mysql -ulibrivox -plibrivox librivox_catalog < roles/blog+catalog/files/librivox_catalog.schema.sql - -### Share folders - -To access the LibriVox files (blog, catalog, forum, wiki) from the IDE, -configure some shared folders in the VirtualBox machine settings. - - # TODO - mount /mnt/sf_/... /librivox - -### Summary - -You have the LibriVox environment basically running now. -Visit https://librivox.org/ to check it out. -Most of the LibriVox components don't work yet: - -* The blog is an uninitialized WordPress installation, with no content. -* The catalog is empty, so searching will always result in "No result". -* The forum doesn't work since the database is missing. -* The wiki doesn't work since the database is missing. - -As said above, this guide is not yet finished. But it's better than nothing. - -# Deinstall LibriVox - -If you want to get rid of the whole local LibriVox installation, follow these steps: - -* In VirtualBox, remove the virtual machine and all its files -* Deinstall VirtualBox -* Clean up the `hosts` file -* Remove the certificate from the trust store