Add updated remote host install instructions

playbooks/archivematica-bionic/README.md

@@ -1,15 +1,16 @@
-# Archivematica playbook
+# Archivematica Installation
+
+## Vagrant install
 
 The provided playbook installs Archivematica on a local vagrant virtual
 machine.
 
-## Requirements
+### Requirements
 
 - Vagrant 1.9 or newer
 - Ansible 2.2 or newer
 
-## How to use
-
+### How to use
 
 1. Download the Ansible roles:
   ```
@@ -63,3 +64,142 @@ plugin that installs the host's VirtualBox Guest Additions on the guest system:
   ```
 
 For more archivematica development information, see: https://wiki.archivematica.org/Getting_started
+
+## VPS Install, or How to Deploy Archivematica to a Single Node
+
+This section describes how to deploy Archivematica to a remote server
+(i.e., virtual private server, VPS), such as an AWS EC2 instance or Digital Ocean
+Dropler.  It assumes that you have basic proficiency with the Unix command-line
+and that you have the following installed:
+
+- git
+- Python
+- [Ansible](http://docs.ansible.com/ansible/intro_installation.html)
+
+For this tutorial, we'll assuming that you have a [DigitalOcean account](https://www.digitalocean.com/community/tutorials/how-to-create-your-first-digitalocean-droplet-virtual-server) and that you have
+created a new droplet. Other VPS providers should work similarily.
+
+Note that Ubuntu 18.04 only includes Python 3 by default. You will need to install Python 2.7 after you set up your droplet, by logging in and issuing an `apt install python2.7`
+command.
+
+1. Clone the git repository that contains the Ansible configuration files which
+   will be used to install Archivematica and all of its dependencies onto the
+   system::
+
+    $ git clone https://github.com/artefactual/deploy-pub.git
+
+2. Download the Ansible roles that will install Archivematica and its
+   dependencies::
+
+    $ cd deploy-pub/playbooks/archivematica-bionic
+    $ ansible-galaxy install -f -p roles/ -r requirements.yml
+
+3. Create a ``hosts`` file to tell Ansible the alias for our server (``am-local``),
+   its IP address and that we want to use the root user (where
+   ``xxx.xxx.xxx.xxx`` is the droplet's actual IP)::
+
+    $ echo "am-local ansible_host=xxx.xxx.xxx.xxx ansible_user=root" > hosts
+
+4. Modify the Ansible config file ``ansible.cfg`` to point to our ``hosts`` file::
+
+    $ cat ansible.cfg
+    [defaults]
+    nocows = 1
+    inventory = hosts
+
+5. If you do not have a SSH key, create one now (accepting the defaults)::
+
+    $ ssh-keygen -t rsa
+
+6. Copy the output of the above command to your clipboard and add it to the
+   server's allowed hosts. For Digital Ocean, save it to your Droplet in the
+   ["New SSH Key" web interface](https://cloud.digitalocean.com/settings/security)::
+
+    $ cat ~/.ssh/id_rsa.pub
+
+7. Use Ansible to create a new user on our server. Create a file (an Ansible
+   playbook) called ``user.yml`` which has the content indicated by
+   the output of ``cat`` below::
+
+    ```yaml
+    $ cat user.yml
+    ---
+    - name: create artefactual user
+      hosts: am-local
+      tasks:
+
+        - name: add artefactual user
+          user: name=artefactual shell=/bin/bash
+
+        - name: add ssh keys to the corresponding user
+          authorized_key: user=artefactual
+                          key="{{ lookup('file', '~/.ssh/id_rsa.pub') }}"
+
+        - name: configure passwordless sudo for the artefactual user
+          lineinfile: dest=/etc/sudoers
+                      state=present
+                      regexp='^artefactual ALL\='
+                      line='artefactual ALL=(ALL) NOPASSWD:ALL'
+                      validate='/usr/sbin/visudo -cf %s'
+    ```
+
+The ``user.yml`` file creates a user called "artefactual" on the droplet, adds
+your public key (assumed to be in ``~/.ssh/id_rsa.pub``) to the droplet, and
+allows the artefactual user to run commands using ``sudo`` without a password.
+Choose a different username than "artefactual" if you want.
+
+To run the user playbook, use the command:
+  
+  ```
+  $ ansible-playbook user.yml
+  ```
+
+8. Modify the ``hosts`` file to use the appropriate (e.g., ``artefactual``) user::
+
+    ```bash
+    $ cat hosts
+    am-local ansible_host=xxx.xxx.xxx.xxx ansible_user=artefactual
+    ```
+
+9. Confirm that you can access the Digital Ocean droplet via SSH::
+
+    `$ ssh [email protected]`
+
+10. And via Ansible::
+
+    ```bash
+    $ ansible am-local -m ping
+    am-local | SUCCESS => {
+        "changed": false,
+        "ping": "pong"
+    }
+    ```
+
+11. Install and deploy Archivematica and its dependencies::
+
+    `$ ansible-playbook singlenode.yml`
+
+The above command will take several minutes. If successful, the final output
+should indicate ``unreachable=0 failed=0``.
+
+Note: the ``ansible-playbook singlenode.yml`` command may fail initially. If it
+does, try it again.
+
+12. Confirm that Archivematica and its dependencies are installed and working
+    by navigating to your Digital Ocean droplet's IP address
+    (http://xxx.xxx.xxx.xxx). The Archivematica Storage Service should be being
+    served at the same IP on port 8000, i.e., http://xxx.xxx.xxx.xxx:8000.
+
+The default username and password for accessing the Storage Service are "test"
+and "test". Once you log in, go to the "Administration" tab, then click "Users"
+on the lefthand column, then click the "Edit" button of the "test" user, then
+copy the API key at the bottom of the page to your clipboard.
+
+Then navigate to the Archivematica dashboard (http://xxx.xxx.xxx.xxx), fill in
+the form, and click "Create". When communication with the FPR Server has
+completed, click the "continue" button. Now enter the API key that you copied
+from the Storage Service and click the first button, the one labelled "Register
+with the storage service & use default configuration."
+
+You can test that your Archivematica installation works by performing a sample
+Transfer and Ingest.