This is a guide to install all needed systems, tools, download source code and get going with the development.
The stuff will be installed on your local computer and you will be able to develop and debug the system running as localhost.
The guide has the following parts:
- Install php, MySQL and Apache server
- Install WordPress
- Install Git
- Install Bitcoin Bank plugin
- Install Pay-Per-Page-Click plugin
- Install Banking App
- Install php IDE and start debugging
- Install MySQL browser/editor
Note! As the system is in continuous development, parts of this guide and screen shots may differ.
Install php, MySQL and Apache web server
If you are using Linux, php, MySQL and Apache may already have been installed on your computer. If not there are a lot of good guides for installing these on the Internet. Ubuntu users may try the LAMP package (Linux-Apache-MySQL-php):
Basically, (at least for for Ubuntu users), this command line should do it all:
sudo apt-get install lamp-server^
Windows user may install the Windows equivalent of LAMP, WampServer:
Test Apache server
After LAMP or WAMP has been installed and started, your machine works as web server. By default there may be index page prepared by the installation and you should be able to read this as localhost in your web browser:
To play with the Apache server, you can replace the default index file with your own index file. Search for the web content folder, on Windows it is probably located in a path like C:\wamp\www\. On Linux it may be found in the /var/www/html/. Make php script and put it in index.php to verify the php is working.
For those new to php, check out this tutorial: https://www.tutorialspoint.com/php
As a test that apache and php is working, you can try create a php script file named test.php and put it in the www content folder:
<?php echo '<html>'; echo '<head>'; echo '<title>PHP Test</title>'; echo '</head>'; echo '<body>'; echo '<p>Hello World</p>'; phpinfo(); echo '</body>'; echo '</html>'; ?>
This script run phpinfo() function, which prints out status information for your php installation. The script will be accessible here:
Enable apache to read from your user folder
When coding in Linux, it will be more convenient to do that from your local user folder. (Windows user may skip this part.)
Configure Apache2 to read from your local public folder. This configuration is distro depended. You may need to google for instruction for your distro. This links to instructions for Ubutu:
For Ununtu users, this is basically what needs to be done:
Remove or comment out some lines in your Apache2’s php configuration. (The filename may vary depending on php version.)
$ sudo nano /etc/apache2/mods-available/php7.0.conf
Remove or comment out the following lines:
#<IfModule mod_userdir.c> # <Directory /home/*/public_html> # php_admin_flag engine Off # </Directory> #</IfModule>
Enable Apache2 userdir module and then restart Apache2
$ sudo a2enmod userdir $ sudo service apache2 restart
Create a public_html folder and test it by copy your previosuly created test.php file into it:
This file is now accessible in your browser. (Replace my_user_name with your actual user name):
Setup and test MySQL server
Verify that MySQL is up and running. For those new to MySQL, check out this tutorial:
Create a database and prepare a datbase user account for the WordPress system.
In command line, start mysql:
(By default WAMP create a user “root” with no password. You should set a password yourself. In Window installation, WAMP did not add search path, so you must locate mysql.exe yourself. It is located in your installed wamp folder.)
mysql -u root -p
Create a new database and name it “wordpress”:
mysql> CREATE DATABASE wordpress; Query OK, 1 row affected (0,00 sec)
You can verify that the new database has been created by listing all databases:
mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | performance_schema | | sys | | wordpress | +--------------------+ 5 rows in set (0,00 sec)
Create a new database user account named “wordpress”. Create a new password and replace it for the word “password”:
mysql> CREATE USER 'wordpress'@'localhost' IDENTIFIED BY 'password'; Query OK, 0 rows affected (0,00 sec)
Verify that new user exist by listing all database users, the list will be something like this:
mysql> SELECT User,Host FROM mysql.user; +------------------+-----------+ | User | Host | +------------------+-----------+ | debian-sys-maint | localhost | | mysql.sys | localhost | | root | localhost | | wordpress | localhost | +------------------+-----------+ 4 rows in set (0,00 sec)
Give the newly created user privileges to access the wordpress database:
mysql> GRANT ALL PRIVILEGES ON wordpress.* TO 'wordpress'@'localhost'; Query OK, 0 rows affected (0,00 sec)
Test the newly created database user account. Quit mysql and restart mysql client with the newly created user:
mysql> quit Bye mysql -u wordpress -p
When listing all databases, the list should only include the newly created wordpress database and the information_schema database:
mysql> SHOW DATABASES; +--------------------+ | Database | +--------------------+ | information_schema | | wordpress | +--------------------+ 2 rows in set (0,00 sec)
Install GD support for php
Bitcoin Bank plugin require GD support in php. This is used to create png images of cheques.
For Linux, run this installation command and restart Apache2. (library name varies depending on version.):
sudo apt-get install php7.0-gd sudo service apache2 restart
By refreshing the test.php file, GD module should now be enabled. Search for the text “GD Support” and verify it is set to “enabled”.
This part will mostly be the same procedure for Linux and Windows, except for the path to the www folder.
Download and install WordPress:
Download the latest WordPress package from here:
Extract the compressed package into the web content folder. It is recommended to store the WordPress files in a sub-folder below the www folder. This will easily allow for several WordPress instances to run simultaneously. During this guide we will install two WordPress system, so we put the first one in wordpress1 folder:
Linux: ~/public_html/wordpress1/ Windows: C:\wamp\www\wordpress1\
Note! For Linux users, ensure that the wordpress1 folder has right ownership and permissions. For Apache2 to be able to read and write to the public_html folders, set permissions to 755 and ownership to www-data:
$ sudo chmod 755 -R wordpress1 $ sudo chown -R www-data:www-data wordpress
Note: It is not required that all files and folders are owned by www-data, only those that WordPress will need to write to. When coding it may be more convenient to have some of your files owned by yourself.
Start and configure WordPress:
If Apache server is now up and running you should now be able to start WordPress from your web browser:
For Linux user, running WordPress in the user folder, replace my_user_name with your own user:
First time you start WordPress, you will be asked to select language and create the first user:
Enter MySQL database name, user name and user password you created during the MySQL installation. (This is the user name and password is to access MySQL database, not to log into WordPress as a user.)
If you are running several WordPress instances and using the same MySQL database, you need to have different database table prefix for each WordPress instance. Change the Table Prefix to something unique.
This step is actually creating a wp-config.php file into your WordPress’s root folder. Alternatively you can also create this file manually yourself. A template wp-config-sample.php is provided as an example. If wp-config.php is correctly created, then this dialog step will be skipped.
If WordPress is able to access the database, show this success message. Otherwise it will complain.
Press “Run the Install” and move on.
Give your site a name and make a user:
You must provide a e-mail address for the user created, however, if your computer have no SMTP server running, you machine will not be able to send e-mail.
If configuration and user creation succeeded you will see this screen:
Now you can try to view your site from:
Pretty simple, but working.
You can log-in to WordPress with your newly created user:
After log-in you will enter the admin panel.
Basically your WordPress installation is now up and running. If you are new to WordPress, you should familiarize yourself with the system. Play around and create some posts, pages, menus etc.
Even it is possible to download the source code from GitHub without using Git, it is highly recommended to start using Git immediately. You will need Git to commit and push new code updates to the repository and with Git you can more easily update your repository clone as other developers commit code.
If you have not installed Git on your computer you can download it from here:
If you are not familiar with Git you should read some of the Git documentation and learn a few of its basic function before proceeding.
For windows users, there exist a very convenient Shell Interface to Git, TortoiseGit. With that interface you can operate Git from your file browser:
Install Banking App plugin
There are tons of plugins available for WordPress and it is very easy to install them from the WordPress Plugin Directory in the Plugins menu in the admin panel.
However, the Banking App plugin and Pay-Per-Page-Click plugin have not been released to WordPress Plugin Directory yet. The plugins’ source code are stored in Git repositories at Github. These needs to be downloaded and installed manually.
Clone/download Bitcoin Bank plugin source code:
Clone (i.e. download) the Bitcoin Bank repository from GitHub. Bitcoin Bank repository can be found here:
Go to wordpress’ plugin folder:
The git command to clone the repository:
git clone https://github.com/bitcoincheque/bitcoinbank-wordpress-plugin.git
When done right the bitcoin_bank.php file will be located in the bitcoinbank-wordpress-plugin folder.
Activate Bitcoin Bank plugin:
If the bitcoin_bank.php is put in the right folder in the plugin folder, WordPress will automatically detect a new plugins is present. Bitcoin Bank plugin will appear in the Plugins menu in the admin panel:
(The plugin list has two other plugins that are installed in WordPress by default.)
Click Activate on the Bitcoin Bank plugin.
The activation will create the needed database tables used by the Bitcoin Bank plugin.
If successfully activated, the panel will tell that “Plugin activated”:
Configure Banking App
You will need to prepare pages that will display the Bitcoin Bank functions.
In the admin panel, create a new page named “Transaction”. In this page write the following short code:
This short code will display a list of Account transaction on the Transaction page. The page may also contain other text besides the short codes. When page is done, press Publish.
A WordPress short code is a macro that will call a php function provided by the WordPress system or an installed plugin. More information about WordPress short codes API can be found here: https://codex.wordpress.org/Shortcode_API
For convenience you should add the Transaction page to the front-page’s main menu. This can be done in the Appearance / Menus setting in the admin panel. (When creating the first menu, you must set that menu as “Primary Menu” to make it visible on the front-page.)
Since we will run several WordPress instances on out computer, you should change the background color to easily be able to tell which is one. Colors are changed in the Customize panel selected from the Appearance menu in the admin panel.
After Transaction page has been created, you can return to the frontage and see the transactions:
The transaction list only show one transaction, the INITIAL transaction that is setting the balance to 0.
NOTE: The Bitcoin Bank has not implemented support for actually doing the Bitcoin transaction. The Bank is currently using a fake currency named TestBTC.
To enjoy all bank functions more pages must be created with short codes. Create the following listed pages and put the listed short code into them:
The full list of implemented short codes can be found in the bitcoin_bank.php file at its bottom. The function add_shortcode adds the short code to the WordPress system.
Test Bitcoin Bank by drawing a cheque
Now the front-page has been extended with a lot of menu items. Try create a cheque from the Draw Cheque menu:
After pressing Create Cheque, the cheque will be created and displayed:
The GD library is required to create the cheque image. If the image is not loaded, you should check your GD support (See above instructions.)
If your computer has SMTP installed and WordPress is configured to send e-mails, then you can press Send e-mail to send the cheque.
In the Transaction List you can now that a transaction has taken place.
Install SMTP server:
To make the Banking App able to send e-mails, SMTP must be installed and WordPress must be configured to send e-mails.
Most Linux server hosts already has SMTP installed and WordPress will automatically detect it. When running WordPress locally this is not usually the case, especially not for Windows.
For testing purpose it may be easier to use your personal e-mail’s SMTP server. There is a plugin “WP Mail SMTP” that can reconfigure WordPress to use an external SMTP server:
It can be downloaded and installed from the Plugins menu in the admin panel. Select Add New in the Plugins menu, search for “WP Mail SMTP” and select Install Now and Activate.
Configure the plugin. Select Settings and Email. The plugin author’s homepage can give advice for configurations: http://www.callum-macdonald.com/code/wp-mail-smtp
When WordPress is working with WP Mail SMTP, the Bitcoin Bank will be able to send e-mails. Try draw a new cheque and send it by e-mail.
Install Pay-Per-Page-Click (PPPC) plugins
You can either install the PPPC plugin in the same WordPress installation as the Bitcoin Bank, or you can install a new instance of WordPress that runs parallel with the existing one and install PPPC plugin in that.
In this guide we will create a new WordPress instance in the following folder:
Follow the Install WordPress guide above and return back when done.
Clone/download PPPC plugin source code:
Same procedure applies for the PPPC plugin as the Bitcoin Bank.
Repository can be found here:
Git clone repository:
$ cd wordpress2/wp-content/plugins $ git clone https://github.com/bitcoincheque/bitcoin-pay-per-page-wordpress-plugin.git
Activate PPPC plugin:
After the PPPC plugin source code has been downloaded into the WordPress’s plugins folder, it will appear in the Plugins menu in the admin panel. From here select Activate.
(This is the same procedure as with the Bitcoin Bank plugin activation.)
Configure PPPC plugin
After activation, the Pay Per Page menu will appear in the admin panel. As a minimum you will need to configure three settings:
- Set your Bitcoin Wallet address.
This will be the address where your payment will be sent to. (Currently this feature is not completed. If you have no Bitcoin Wallet, just write some random letters to make a fake address)
- Set the Instruction and URL to the recommended Bitcoin Bank.
This Instruction and URL will be used if no Banking App has been installed. When payment is required, the instruction will be displayed to the visitor, and the link to the payment page at the bank will take the visitor the that bank for payments.
If you have followed this guide, your bank’s payment page will be located here:
To get the URL right, you can open your Bitcoin Bank and copy the URL form the payment page. This payment page must be the page that has the [bcf_bitcoinbank_payment] short code.
(In case the Banking App is installed in your web browser, this instruction and link will not be displayed. In that case the payment will be handled directly by the Banking App.)
- Set a list of trusted banks.
These are the banks that you will trust issued cheques from. Put one bank URL address on each line.
For the purpose of following this guide, you will only need to add one bank, your local one running on the other WordPress instance.
Make a page that requires payment
In the newly installed WordPress, there exist a page called Sample Page. For demonstation you can use this page, or create a new page.
Anyway, in the page that has some text content that you want to charge payment for, add the short code [require_payment] some place down in the text. Then the part below that short code will only be visible for visitors that has made a payment.
This is an example page. It's different from a blog post because it will stay in one place and will show up in your site navigation (in most themes). Most people start with an About page that introduces them to potential site visitors. It might say something like this: Hi there! I'm a bike messenger by day, aspiring actor by night, and this is my website. I live in Los Angeles, have a great dog named Jack, and I like piña coladas. (And gettin' caught in the rain.) ...or something like this: [require_payment] The XYZ Doohickey Company was founded in 1971, and has been providing quality doohickeys to the public ever since. Located in Gotham City, XYZ employs over 2,000 people and does all kinds of awesome things for the Gotham community. As a new WordPress user, you should go to your dashboard to delete this page and create new pages for your content. Have fun!
Also remember to add the Sample Page to the menu, for easy access.
Test page payment:
Return to your front page, and select the newly created page:
It will look something like this:
The short code is replaced with a message asking you to make a payment. (In fact, this is really not a short code in the terms of WordPress, but rather just a text string that the plugin will search for when rendering the page.)
If you have not installed the Banking App, the PPPC plugin it and will give you the instructions as set by the Recommended Bitcoin Bank setting in the admin panel. A link will be displayed that will take you to the recommended bank for payment processing.
Press the link and you will be taken to your bank on the other WordPress instance.
NOTE: To make this test run without hassle, you will be needed to stay logged-in on the WordPress running the Bitcoin Bank. Otherwise you will be asked to first log-in and then go back to the payment page. The Bitcoin Bank is currently lacking a re-direct feature to show the payment page after log-in.
The price and the receiver’s name will be displayed. To confirm the payment, press “Make Payment”.
The bank will now process the payment against the PPPC plugin. If payment was successful, it will display this confirmation message.
Press “Return to Site” to return back to the page that you have paid for and continue reading the remaining text.
The plugin will remember your payments until the cookie expires. You don’t need to be logged in as long as you are using the same browser.
If you log-in, the plugin also will remember your user name, and allow you to log-in from another computer or another browser and read the full page from there.
To retry the test, you can either create another user, or create another page that requires payments, or use another browser or computer.
For convenience during development it is also possible to remove all payments. The PPPC plugin has a short code, that when called upon, will forget all payments. To use this feature, make a new page, give it a name like “Remove Payments”, and put the short code [remove_payments] in it. You can also put the page in the menu for easy access. When the page is displayed, PPPC will forget all payments.
In you return to your bank, you now can list the transactions and cheques that has been issued and used for the payments.
Install Banking App
To enable the instant one-click payment feature of the payment system, you will need to install the Banking App into your web browser. The Banking App is currently only available for Google Chrome and Chromium, so you may first need to install one of those browsers.
The Banking App may be downloaded and installed directly from Google Marketplace. This is the the default installation for end users. Developers should clone/download the source code from GitHub.
Install from Chrome Marketplace
Go to Chrome Marketplace and the Banking App’s page:
Press Add to Chrome. The Banking App will be installed as a Chrome extension and a new icon will appear on the top menu.
Log into your Bitcoin Bank
more to come…
Install recommended IDE
The development is not bound to any development tools. However, there are some pretty good IDE’s that can be recommended. JetBrains’ PhpStorm and WebStorm are some really good ones.
The Bitcoin Cheque development team has been fortunate and supported by JetBrains with a number of user licenses. Active open-source developers may apply for one of these licenses. Send a mail to mail (at) bitcoincheque . org.
Fro Linus users, PhpStorm and WebStorm require the following libraries and packages to be installed:
The PhPStorm and WebStorm editors itself can be downloaded from