# QEMU-autobuild

## TL;DR

To get the VM running:

1. On host: `$ qemu-system-x86_64 -m 1024 -enable-kvm -k en_us -hda WooTaler.img -net nic -net user,hostfwd=tcp::9999-:80`

2. Log on as `root:wootaler`

3. On guest: run `./buildWooTalerServer.sh`.  

This README (or a version created as of VM build time) is also visible in `/root` on the VM.  `git pull` inside the `/root/woocommerce-taler` directory will pull new versions of this README and the script, which might be good or bad.

## Description

This file contains details about the sample QEMU VM and how to build it into a WordPress/WooCommerce/GNU Taler ('WooTaler') server.

This README and the WooTaler.img QEMU VM are designed to meet internal needs of the GNU Taler project.  If your goal is to build your own working WooTaler webshop, please examine the files in the `server-build/generic-debian` folder in the following repo:  `git://git.taler.net/woocommerce-taler.git`.

**Are you viewing this from inside the VM?**  You may want to skip down to `Updating the VM` in that case.

## WooTaler VM Premises:

* Requires an x64-compatible QEMU environment
* Language: English
* Keymap: US
* Timezone: UTC
* The VM in this repo is build on Debian 10.3.0 stable
* Hostname: WooTaler
* root password: `wootaler`
* default (sudo) user:pass  `wootaler:wootaler`
* SSH Server is *not* installed
* Disk:
  - All files in one partition
  - 256MB linux-swap partition
* Also present on the server is a (possibly outdated) copy of `buildWooTalerServer.sh`, the script that automates installation of the WooTaler VM.  As of this time, the pdated version (and possibly updated VMs) are in the Git repo under `woocommerce-taler.git/server-build/QEMU-autobuild/`.

**IMPORTANT** To use this VM, you should understand basic Debian systems administration including updates, password changes, firewalls, and you should not use this VM in its default state without customization.


## Starting the VM

On a system that has 64-bit QEMU installed, run:

`$ qemu -m 1024 -enable-kvm -k en_us -hda WooTaler.img -net nic -net user,hostfwd=tcp::9999-:80`

Notes:

* You may need to specify the binary as `qemu-system-x86_64`
* You can specify the amount of ram with the `-m` flag.  `-m 1024` provides 1GB (recommended)
* If the parent system does not have kvm installed in the kernel, remove the `-enable-kvm` flag
* `-k en_us` specifies a US English keymap, which is the default for this VM.  Change as necessary.

After starting the VM, log in using the information above.

### Understanding the VM

The VM is a very basic Debian 10 command-line system.  No SSH or other services should be installed.  In addition to the most basic Debian system, these packages are also installed:

`screen tmux git w3m secure-delete rsync sudo pwgen net-tools`

In the `/root` directory, there is a selective clone from `git.taler.net/woocommerce-taler.git` that includes this `README.md`, the main `buildWooTalerServer.sh` script that will install WooTaler, and other supporting files.  The script will assume this path.  There is also a symlink from the README and the script into the `/root` directory.

### Updating the VM

It is smart for some reasons, and not smart for others, to do basic Debian updates at this time.  The script will not do this because it is meant to require little user input, but Debian updates (done correctly) require this.  Update command (as root):

`# apt update && apt -y dist-upgrade && apt -y autoremove && apt -y clean`

**WARNING**: If Debian upgrades PHP to a newer version, you will have to enter that value when running `buildWooTalerServer.sh`.

### Customizing the VM

Now is a good time to update the language, timezone, and anything else you wish.  Examples:

`# dpkg-reconfigure tzdata` - Set timezone
`# dpkg-reconfigure locales` - Set languages

You might also set the password for the `root` and `wootaler` users.  The `pwgen` command line tool is installed on this VM if you want to generate reasonably secure passwords.

### Updating the buildWooTalerServer.sh script and supporting files

`buildWooTalerServer.sh` is the script that will autobuild the server.  But the copy on the VM was created when the VM was created.  To update this from within the VM:

1) Log in as root
2) `# cd woocommerce-taler/server-build/QEMU-autobuild`
3) `# git pull`

**WARNING**: updating the script could cause a conflict if you are running an older VM than the script was built for.  (Also, once you make the script executable, Git will consider this a "change" that requires stashing - or `chmod -x`.)

## Using your own VM

If you do not use the WooTaler.img-Base VM image but create your own, you'll want to pull some files from the repo.  As follows (as root):

```
cd
git clone -n git://git.taler.net/woocommerce-taler.git --depth 3
cd woocommerce-taler
git checkout HEAD server-build/QEMU-autobuild/
cd && ln -s woocommerce-taler/server-build/QEMU-autobuild/buildWooTalerServer.sh . && ln -s woocommerce-taler/server-build/QEMU-autobuild/buildWebstore.sh .
chmod +x ~/buildWooTalerServer.sh && ~/buildWebstore.sh
```

## Running the buildWooTalerServer.sh script

The `buildWooTalerServer.sh` script performs the following actions:

1. Installs apache2, php, mariaDB, and supporting files
2. Configures apache2 to handle PHP, and to serve a WordPress site on port 9999
3. Installs and Configures WordPress
4. Creates the mariaDB database
5. Passes on to `buildWebstore.sh` which uses wp-cli to build the webstore in more depth.
6. Provides messages when complete that there is still some GUI work to do.

(**HINT**: The VM has `screen` and `tmux` installed by default.)

As root, run:
`# chmod +x /root/buildWooTalerServer.sh && cd && ./buildWebstore.sh`

Up, up, and away!

## Manual Config

After the script runs, you will have to configure a few things in the WP GUI manually.  The script will print these instructions out but that's annoying so here they are again:

### 1. You must configure the store to accept KUDOS.  To do this:'
   a. Log into the WooTaler site in your **host** system at 127.0.0.1:9999/wp-admin, using the admin username and password you set during this installation.
   b. Navigate the left menu to Snippets > Add New.
   c. Add "KUDOS Support" using the code in git://git.taler.net/woocommerce-taler.git/server-build/QEMU-autobuild/KUDOS-WooCommerce-Support.php.txt
   d. Click the radio buton for "Run snippet everywhere" and click "Save Changes and Activate"

### 2. You must set up WooCommerce defaults.  To do this:'
   a. Log into the WooTaler site in your **host** system at 127.0.0.1:9999/wp-admin/.
   b. Click on WooCommerce > Settings
   c. Under the "Payments" tab, enable and then "Set up" "GNU Taler Gatway"
   d. Navigate to 127.0.0.1:9999/wp-admin/admin.php?page=wc-setup and go through the annoying WooCommerce setup wizard (Note that many options are enabled by default, and you have to turn them off.)

## Using the site

Now you can view your webstore on the **guest** machine at `localhost` (port 80), or the **host** machine at `127.0.0.1:9999`.