01) Installation

Hamawardz Installation #

Step 0: Get a domain, or a subdomain #

You’ll need one for this piece of software. The internet provides plenty of options.

Step 1: Install Apache, PHP and Composer #

If you are using shared hosting, skip this step, but make sure composer exists on your hosting provider.

If not, this is just the list of commands to install all those prerequisites on a new blank current Ubuntu system. You’ll find plenty of extensive tutorials on how to do that, this is just here to get you started asap.

sudo apt-get update -y
sudo apt-get install apache2 -y
sudo add-apt-repository -y ppa:ondrej/php
sudo apt-get update -y
sudo apt-get install libapache2-mod-php php php-common php-xml php-mysql php-pgsql php-gd php-opcache php-mbstring php-tokenizer php-json php-bcmath php-zip php-sqlite unzip -y
sudo a2enmod rewrite
sudo service apache2 restart
curl -sS https://getcomposer.org/installer | php 
sudo mv composer.phar /usr/local/bin/composer
composer --version

If you like to use MySQL instead of SQLITE as a backend, also install MySQL.

You really don’t have to though, because for 99,5% of users, SQLITE should be just fine.

sudo apt-get install mysql-server -y
sudo mysql_secure_installation

Step 2: Configure Apache #

If you are using shared hosting, set the root folder of the webpage to the public subfolder and skip the rest of this step.

First, create a vhost configuration file for hamawardz. Of course, you can substitute the name of the file with whatever you like:

sudo nano /etc/apache2/sites-available/hamawardz.conf

In the file, create the virtual host. Of course, customize directories, Domains and Admin-Emails to your liking.

<VirtualHost *:80>
    ServerAdmin admin@example.com
    ServerName mydomain.com
    DocumentRoot "/var/www/hamawardz/public"

    <Directory /var/www/hamawardz/public>
    Options Indexes MultiViews FollowSymLinks
    AllowOverride All
    Order allow,deny
    allow from all
    Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Activate the site and reload apache.

sudo a2ensite hamawardz.conf
sudo service apache2 restart

Step 3: Install hamawardz #

Clone this repo, install all dependencies, copy you environment file and generate your app key.

If you are using shared hosting, scrap the sudo -u www-data part from each command from here (also in the following steps).

cd /var/www
sudo -u www-data git clone https://github.com/DB4SCW/hamawardz hamawardz
cd hamawardz
sudo -u www-data composer install --no-dev
sudo -u www-data cp .env.example .env
sudo -u www-data php artisan key:generate

Open the .env file:

nano .env

Change the database configuration, depending on your choice of database. You can choose one of the following popular examples or provide your own:

1) SQLITE #

Please change the values to reflect your installation. DB_DATABASE is the filename of your sqlite file inside the database subdirectory:

DB_CONNECTION=sqlite
DB_DATABASE=database.sqlite

Afterwards, create the sqlite file:

sudo -u www-data touch /var/www/hamawardz/database/database.sqlite

2) MySQL #

set your MySQL login data. Use root or a user that can change the database schema. If the hamawardz-database doesn’t exist yet, create it first:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=hamawardz
DB_USERNAME=root
DB_PASSWORD=RootP#ssword

Step 4: Configure your software environment #

Have a look at the rest of the env file and change other values according to your needs, e.g.:

  • APP_ENV (e.g. production or local -> for actual live service, choose production)
  • APP_DEBUG (set to false to hide internal errors -> please do that in live service)
  • APP_URL (your URL)
  • APP_IMPRESSUM_URL (sets the impressum url in the footer, defaults to homepage if empty)
  • APP_DATA_PROTECTION_URL (sets the data protection declaration url in the footer, defaults to homepage if empty)

If you like, you can place a file called privacy.html in the public folder of hamawardz to contain your data protection declaration. You can link there in APP_DATA_PROTECTION_URL like this: https://your.site.here/privacy.html.

If you like, you can place a file called impressum.html in the public folder of hamawardz to contain your impressum. You can link there in APP_IMPRESSUM_URL like this: https://your.site.here/impressum.html.

Those two exact(!) file names are explicitly allowed to be placed there and will NOT be overwritten by any future update.

Step 5: Prepare the database and the upload folder #

Migrate the database and create the link for storage and the folder for award background images and set read-write permissions on that just to be sure. After that, restart apache for good measure.

If you are using shared hosting, scrap the sudo -u www-data part from each command. Also, omit the chmod command entirely.

cd /var/www/hamawardz
sudo -u www-data php artisan migrate
sudo -u www-data php artisan storage:link
sudo -u www-data mkdir public/storage/images
sudo chmod a+rw public/storage/images
sudo service apache2 restart

Step 6: Secure your hamawardz installation #

Configure your apache server with a Let’s Encrypt SSL certificate using certbot (plenty of guides out there), or place your install behind a reverse proxy (if you choose that, I think you know what to do already).

Step 7: Finished #

Login to Hamawardz, using username “administrator” and password “welcome#01”. Please remember to change that password immediately.

Have fun!

Updating hamawardz to a new version #

Just cd into your folder, git pull and afterwards, migrate the database. You are up and running the newest version!

If you are using shared hosting, scrap the sudo -u www-data part from each command.

cd /var/www/hamawardz
sudo -u www-data git pull origin master --rebase
sudo -u www-data php artisan migrate
sudo -u www-data composer install