path: root/server-build/generic-debian/Server-Build-Instructions.md

# Purpose of this document

This document is an instruction manual to install WordPress, WooCommerce, and the GNU Taler WooComerce plugin on a fresh Debian 10 system and have it serve a GNU Taler-enabled WordPress/WooCommerce site using HTTPS with a LetsEncrypt SSL certificate or self-signed certificate.

## Assumptions

* The target system for this build is a Debian 10 stable system.

* You have root-level (ex. sudo) access to this system.

* Apache2 will be the default web server.

* Your server will have a domain name such as _domain.com_.  This is necessary for the LetsEncrypt SSL certificate.  If you will use this server locally or using the raw IP address, you may follow the instructions for a self-signed certificate instead.

## Configure firewall

You may use the file in `scripts/ufw-setup.sh` to install ufw (uncomplicated firewall) and automatically open ports 80 and 443 (needed for LetsEncrypt and for access to the WordPress/WooComerce site.)

Alternatively, configure your firewall of choice to accept requests on ports 80 and 443 (and whatever port(s) you may be using to access your server, ex: SSH port 22.)

##  Software from Debian Repositories

Please note that all software can be installed at one time.  The following separations are only to make the instructions more clear.

### Install Apache2

`$ sudo apt install apache2`

### Install PHP and Supporting Packages for Wordpress, Apache2, nginx

`$ sudo apt install php-pear php-fpm php-dev php-zip php-curl php-xmlrpc php-gd php-mysql php-mbstring php-xml libapache2-mod-php

### Install Certbot for LetsEncrypt (optional)

`$ sudo apt install certbot`

### Install mariaDB Database

`sudo apt install mariadb-server`


## Configure SSL Certificate

###  Using LetsEncrypt

#### Get the certificate:

You must have ports 80 and 443 open on your firewall before running certbot:

`$ sudo certbot certonly -d _domain.com_`

Choose to spin up a temporary webserver.

LetsEncrypt will save the certificate and key as:

`/etc/letsencrypt/live/_domain.com_/fullchain.pem` and
`/etc/letsencrypt/live/_domain.com_/privkey.pem`

#### Set the certificate to auto-renew:

Become `root`:

`$ su`

(Now enter the root user's password)

`# crontab -e`

Add these lines to the crontab (please note you can change the date by adjusting this command.  Look up _cron_ jobs for details):

```
# Weekly Certbot Renewal Check
25 11 4 * * certbot renew --rsa-key-size 4096 --pre-hook "service apache2 stop" --post-hook "service apache2 start"
```

### Using a self-signed certificate

If you prefer to use a self-signed SSL certificate (for example, if your server does not have a public IP address), you may use the script in `/scripts/ssl-create-selfsigned.sh`.  You can also do this manually as follows:

`$ openssl req -x509 -newkey rsa:4096 -keyout selfsigned-key.pem -out selfsigned-cert.pem -days 365 -nodes -subj '/CN=localhost'`

Leave off the `-subj '/CN=localhost'` flag if you prefer to add identifying information to the certificate.

The output will look something like this:

```
Generating a RSA private key
.................................................................................++++
..............................................................................................................................................................................................................................................................................................................................................++++
writing new private key to 'key.pem'
Enter PEM pass phrase:
123976305214592:error:28078065:UI routines:UI_set_result_ex:result too small:../crypto/ui/ui_lib.c:905:You must type in 4 to 1024 characters
123976305214592:error:2807106B:UI routines:UI_process:processing error:../crypto/ui/ui_lib.c:545:while reading strings
123976305214592:error:0906406D:PEM routines:PEM_def_callback:problems getting password:../crypto/pem/pem_lib.c:59:
123976305214592:error:0907E06F:PEM routines:do_pk8pkey:read key:../crypto/pem/pem_pk8.c:83:
```

Next, copy the certificate and key to a location where you will keep them permanently:

`$ sudo mv selfsigned-key.pem selfsigned-cert.pem /etc/ssl/certs/``

Remember this location for inclusion in your web server configuration files.


## Configure Apache2

(skip to next section if you are using nginx)

### Apache2 modules

#### Enable modules for Apache2 to support PHP

`$ sudo a2enmod actions fastcgi alias proxy_fcgi php7.3 proxy_fcgi setenvif`

Please note that you may need to change the version from php7.2, depending on your system.

#### Install modules for HTTP -> HTTPS, and SSL

`$ sudo a2enmod rewrite ssl`

#### Restart Apache2

`$ sudo systemctl restart apache2`

### .conf file

Open `assets/wordpress.apache2.conf` and customize for your system.

Save this file as _wordpress.conf_ and put it in `/etc/apache2/sites-available`. To make it active, issue this command:

`$ sudo a2ensite wordpress && sudo systemctl reload apache2`

You may also wish to remove the default `000-default.conf` apache2 configuration with this:

`$ sudo a2dissite 000-default`

Now reload apache2:

`$ sudo systemctl reload apache2`

Now visiting `_domain.com_` in your browser should bring you to the location where WordPress will soon be.  Don't worry that you have an error at this time.  Move on to "Install Wordpress"

## Configure nginx

The nginx webiste has several suggestions for configuring a WordPress site.  Please visit https://www.nginx.com/resources/wiki/start/topics/recipes/wordpress/ or https://wordpress.org/support/article/nginx/ for recommendations.  Or use the nginx conf file in `assets/wordpress.nginx.site`.

1. Copy `assets/wordpress.nginx.site` to your server as `/etc/nginx/sites-available/wordpress.site`

2. Edit the file to specify the path to your SSL certificate, your `server_name` (ex. _domain.com_), and make any other changes you want to make.

3. Activate the config with `$ sudo ln -s /etc/nginx/sites-available/wordpress.site /etc/nginx/sites-enabled/wordpress.site`

4. Restart nginx with `$ sudo systemctl restart nginx`

Now visiting `_domain.com_` in your browser will bring you to the location where WordPress will soon be.  Don't worry that you have an error at this time.  Move on to "Install Wordpress"


## Install WordPress

You are recommended to follow the official Wordpress instructions at https://wordpress.org/support/article/how-to-install-wordpress/

Alternatively, instructions follow:

### Download the latest Wordpress version:

`$ wget https://wordpress.org/latest.tar.gz`

### Unpack to /var/www/wordpress

Untar WordPress to this directory (all files should be in `wordpress/` subdirectory):

`$ sudo tar -xf latest.tar.gz -C /var/www`

Set permissions and ownership:

`$ sudo chmod -R 755 /var/www/wordpress`

`$ sudo chown -R www-data:www-data /var/www/wordpress`

### Create mariaDB database and password

1. (Optional but highly recommended:) Secure the mariaDB installation:

`$ sudo mysql_secure_installation`

You will be prompted to accept some security defaults, and to set the root password.  Make sure to write this down.

2. Create the WordPress database and user

a. Log into the mySQL/mariaDB command line interface

`$ sudo mysql -u root -p`

Enter your password.  You should now be at the `MariaDB [(none)]>` prompt.

b. Create the database:

`MariaDB [(none)]> CREATE DATABASE wordpress;`

c. Create the user to use the _wordpress_ database:

`MariaDB [(none)]> GRANT ALL PRIVILEGES ON wordpress.* TO "wordpress"@"localhost" IDENTIFIED BY "somepassword";`

Please note that you should choose a secure password instead of "somepassword".  You will need to remember this password later when installing WordPress.

d. Flush Privileges

`MariaDB [(none)]> FLUSH PRIVILEGES;`

e. quit

`MariaDB [(none)]> quit`

### Configure WordPress to use the database

`$ sudo cp /var/www/wordpress/wp-config-sample.php /var/www/wordpress/wp-config.php`

Now open your favorite text editor and edit `/var/www/wordpress/wp-config.php`.  Change the values for the `database_name_here`, `username_here`, and `password_here` to match the values you created in mariaDB.

Save this file and exit.

## Test the WordPress installation

At this point, you should have an Apache2 web server, using a LetsEncrypt certificate, pointing to a WordPress installation on your server.

If everything is correct, you should be able to open a web browser to _domain.com_ (or a local IP address if you are not using a public IP) and see a default WordPress site.  If you do not see this, please troubleshoot by looking back over the instructions above.  They have been tested on a Debian 10 system.

If you do see Wordpress, please configure your Wordpress site and proceed to the next step when complete.

Note that if you are using a self-signed certiticate, you can expect to see an error in your browser as your browser will not recognize the certificate.  This is expected for self-signed certificates.

## Install WooCommerce plugin

The WooCommerce project recommends Automatic Installation using the WordPress dashboard.  Those steps can be found here: https://docs.woocommerce.com/document/installation-2/ or here: https://wordpress.org/plugins/woocommerce/#installation

Because manual installation (via command line) still requires the user to log into the WordPress admin interface to "Activate" the WooCommerce plugin, this document will not detail how to install WooCommerce using the command line.  Please follow the recommended GUI-based instructions above.

Continue through the WooCommerce installation wizard.

Note: for this demonstration, the "Storefront" theme has been selected to replace the default WordPress theme.

## Install and Configure the GNU Taler Payment Gateway for WooCommerce plugin

If you are reading this file outside of the `woocommerce-taler` Git respository, you can get the most recent version of the GNU Taler Payment Gateway for WooCommerce plugin by cloning the correct repo:

`$ git clone https://git.taler.net/woocommerce-taler.git`

The plugin itself is in the `plugin/GNU-Taler-Payment-Gateway/` directory.  More information about the plugin can be found in the `plugin/README.md` file and it is released under the GNU GENERAL PUBLIC LICENSE.

### Install the Plugin in WordPress

1. Copy the `GNU-Taler-Payment-Gateway/` directory to `/var/www/wordpress/wp-content/plugins` on your WordPress/WooCommerce server.

Make sure to re-set directory ownership and permissions if necessary:

`$ sudo chown -R www-data:www-data /var/www/wordpress/wp-content/plugins/GNU-Taler-Payment-Gateway/`

`$ sudo chmod -R 755 /var/www/wordpress/wp-content/plugins/GNU-Taler-Payment-Gateway/`

2. Log into your WordPress site at `<your-site>/wp-admin` and navigate to the `Plugins` page; activate the `GNU Taler Payment Gateway for WooCommerce` plugin on this page.

3. In the WordPress main menu, navigate to `WooCommerce` -> `Settings` and then click the `Payments` tab.  Locate the `GNU Taler Gateway` entry and click the `Set up` button to configure the plugin.

### Configure the GNU Taler Payment Gateway

Edit the fields on this page to match your GNU Taler back-end.  To complete this configuration, you will need a GNU Taler merchant account.  If you have not signed up for a merchant account, please contact your Taler server systems administrator for authorization in the form of an API key.

`Enable/Disable` - Enable or disable the GNU Taler Payment option
`Title` - This is what the customer will see when choosing payment methods.
`GNU Taler Back-end URL` - This is the location of the GNU Taler back-end used with your site.
`GNU Taler Backend API Key` - When you signed up for a merchant account at your GNU Taler back-end, you should have received an API Key.  
`GNU Taler Payment URL` - This is the URL for your (merchant) GNU Taler Wallet, which you received when you signed up for a GNU Taler merchant wallet.
`Summary text of the order` - This is the text the customer will see when confirming payment.
`Send Merchant Information?` - Select if you want to send your merchant information to the GNU Taler back-end with this transaction
`Name of This Webshop` - Set the name of this webshop that the customer will see during the payment transaction.

Check the first `Enable/Disable` box and click `Save changes`.

#### Adding Custom Currency

If you are using the Taler demo, you must add the KUDOS currency to WooCommerce

1. Install and activate the `Code Snippets` plugin in your WordPress site.

2. Under `Snippets` in the WordPress GUI, choose "Add New`

3. Add the following code (fromthe WooCommerce docs: https://docs.woocommerce.com/document/add-a-custom-currency-symbol/)

```
/**
 * Custom currency and currency symbol
 */
add_filter( 'woocommerce_currencies', 'add_my_currency' );

function add_my_currency( $currencies ) {
     $currencies['KUDOS'] = __( 'KUDOS', 'woocommerce' );
     return $currencies;
}

add_filter('woocommerce_currency_symbol', 'add_my_currency_symbol', 10, 2);

function add_my_currency_symbol( $currency_symbol, $currency ) {
     switch( $currency ) {
          case 'KUDOS': $currency_symbol = 'ク'; break;
     }
     return $currency_symbol;
}
```
**NOTE**: The currency symbol for KUDOS is ク (ku in Katakana)

4. Click `Save Changes` and `Activate`

5. Navigate to `WooCommerce` > `Settings` > `General` > `Currency Options` and choose KUDOS.  `Save changes`


## Final Steps

Now all you need is to add a product.  Navigate to `https://_domain.com_/wp-admin` to see your WordPress dashboard.  In the left-side menu, choose `Products` > `Add New` to add a new product, including setting the price in KUDOS.

When done, `Publish` your page and now all users who visit `https://_domain.com` should be able to buy your new product using GNU Taler, assuming they have a Taler wallet installed.

**NOTE:  Tested but did not work.  See https://bugs.gnunet.org/view.php?id=6144#c15545**