Update the CONTRIBUTING guide

garethsime commented 4 months ago

It took me a fair bit of googling and playing around to get a grip on how librivox-catalog fits together, so I thought I'd start writing some of it down for the next person.

I haven't included any details on the structure of the code itself, but I've included some links out to the CodeIgniter docs, which should go a little way to helping people get started.

garethsime commented 4 months ago

Thanks for taking a look! I'm out for a few days, but I can make the updates when I get home

notartom commented 3 months ago

If you (or anyone else, really) ends up coming back to this, I'd like to get rid of the first person singular ("I") in the couple of spots where it's used. Either using the passive voice, or first person plural ("we").

garethsime commented 3 months ago

No problem, I've raised PR #216 to remove it :slightly_smiling_face:

EDIT: Linked the wrong PR number

peterjdann commented 3 weeks ago

At the request of garethsime, I here include the steps I have taken on a Mac running Ubuntu 22.04 under Parallels Desktop to install the Librivox Catalog development environment.

Install ansible

sudo apt update sudo apt upgrade sudo apt install ansible

Install ansible playbook

cd ~ git clone https://github.com/librivox/librivox-ansible cd librivox-ansible sudo nano inventory.yaml Edit initial entries so they read:

localdev: hosts: 127.0.0.1: Note: I don't know how to represent the appearance of these entries properly here, but the second line is meant to be indented from the first, and the third line indented from the second. It's only the IP address you need to edit. The first and second lines remain untouched.

Run the following command: sudo ansible-playbook --connection=local --inventory 127.0.0.1, --limit 127.0.0.1 localdev.yaml -i inventory.yaml

Install WordPress

Start Firefox. Enter URL http://librivox.org Result: Firefox displays message "Warning: Potential Security Risk Ahead".

Click "Advanced" button, then Accept the "Risk and Continue". Wordpress installation screen is displayed.

I set the following values. There appear to be no wrong answers here! Site title = LibrivoxSite Username = LibrivoxUser Password = LibrivoxPWD Confirm use of weak password: check Your email:

Click "Install Wordpress". [There is no need to log in to WordPress when invited to, once this process has succeeded]

Verify installation

In Firefox, go to http://librivox.org/search Result: The Librivox catalog search page is displayed. Note: You need to enter exactly this URL. Entering "librivox.org" will bring you no joy.

A comment about this process

In practice, it took me hours to get to the point where I realised the process could be (and should be) this simple. I have, however, just installed the Librivox development environment on a second Mac running Ubuntu 22.04 under Parallels Desktop and verified that the above instructions worked for me as written.

garethsime commented 2 weeks ago

Thanks for the write-up, @peterjdann! :slightly_smiling_face:

It's cool to see that the playbooks work well regardless of how the Ansible host is set up (Parallels, Docker, LXC, etc.), so hats off to @notartom for the love that's gone into them

In practice, it took me hours to get to the point where I realised the process could be (and should be) this simple.

Yeah, I found much the same the first time I set it up locally. In hindsight, it's really not that hard, but it felt tricky at the time haha

Note: I don't know how to represent the appearance of these entries properly here[...]

You can use triple back-ticks to start a code block

LibriVox / librivox-catalog