Installation guide

  • This installation guide always references to the latest stable version.
  • If you want to update your installation to another version, read the migration guide.
  • You can help making this open source project more visible on GitHub by starring ⭐ it.

Requirements

  • Server with shell access and cronjobs
  • Webserver - Nginx or Apache
  • PHP => 8.2 (prior to v3.6 PHP 8.1)
  • PHP intl extension INTL_ICU_VERSION >= 50.1
  • PHP bzip2 lib (for automatic database backups) (prior to v3.6: PHP ZipArchive class)
  • MySQL >= 8.0
  • If you cloned the repository from Github: Node.js, npm >= v9 and Composer v2
  • There is an offer for paid support and hosting if you don’t want to spend your time on IT stuff.
  • There are demo installations in German and English. Feel free to test before installing.

1. Setting up your dev environment with Docker

2. Setting up your dev environment without Docker

We strongly recommend using our docker dev environment.

  • If you want to set up a dev environment, clone from Github.
  • After that, you need to manually install composer and npm vendors.
  • The main branch always equals the latest stable version provided on https://www.foodcoopshop.com/download.
  • The only difference is, that the zip file already includes the vendors which were already installed by the following commands): 
    $ composer install
$ npm --prefix ./webroot install ./webroot
  • So run that commands if you cloned from Github.
  • Don’t forget to change app.debug to true in your custom_config.php.

Installing the latest stable version for your live server

Setting permissions 

bash ./devtools/installation/set-permissions.sh

New in v3.6 (April 2023)

If you install a version prior to v3.6, run the commands in this file.

Configuration

  • Copy custom_config.default.php to custom_config.php and add your configuration overrides.
  • The default configuration is found in app_config.php.
  • Set app.cakeServerName to your server, e.g. “https://yourdomain.tld” - NO TRAILING SLASH!

New in v3.6 (April 2023)

app.cakeServerName was changed to App.fullBaseUrl

  • Some configuration is stored in the database and can easily be changed from the admin area: https://yourdomain.tld/admin/configurations (Super Admin account required)
  • More infos

Database Setup

  • Create a new database (e.g. foodcoopshop_db)
  • Define your database configuration in custom_config.php

<= v3.5

New in v3.6 (April 2023)

  • run bash ./devtools/installation/init-database.sh de_DE (locale “en_US” is also supported)
  • Import taxes for Austria: bash ./bin/cake migrations seed --seed AddTaxesAustriaSeed
  • OR Import taxes for Germany: bash ./bin/cake migrations seed --seed AddTaxesGermanySeed

Credentials

Setting up cronjobs

Follow the steps of the cronjob documentation.

Testing your email configuration

  • Once you created a Super Admin account (instructions further down), You can test your email configuration by accessing https://yourdomain.tld/admin/configurations/sendTestEmail in your browser.
  • As all emails are sent via the queue, be sure that you set it up correctly. See cronjob documentation.

Setup security keys

Open your domain https://yourdomain.tld in a browser and follow the steps shown to create secure values for the security salt Security.salt. Set it in custom_config.php

Create the valid Super Admin account

  • Open https://yourdomain.tld/sign-in in your browser and register with your personal email address (down below at “Create account”)
  • After the successful registration go to your database (e.g. using Adminer or phpMyAdmin) and open the table “fcs_customer”. There is one record (with your email address). Change the field “id_default_group” from 3 to 5 and the field “active” from 0 to 1.
  • Open https://yourdomain.tld/request-new-password, type in your email address and press “Send”.
  • With the password that was sent to you by email you are able to login as a Super Admin.

The urls in this section depend on the locale of your installation and therefore may be different for you. The urls are constructed from translatio -settings which can be found in the “/resources/locale/country_CULTURE/default.po” file under the keys “route_sign_in” and “route_request_new_password”. Example for “de_DE”:

  • Sign-in: https://yourdomain.tld/anmelden
  • Request-new-password: https://yourdomain.tld/neues-passwort-anfordern

Customizing CSS

  • Change app.debug to true in your custom_config.php so that the assets (css and js) are loaded from the actual files in /css and /js (and not from /cache).
  • To re-build the assets in /cache for production, run composer build

If you downloaded the package with installed vendors from foodcoopshop.com/download, you get a “Missing Plugin DebugKit” exception when you turn app.debug to true. If you can’t install composer on your server, download the package from https://github.com/cakephp/debug_kit and copy it into the plugins folder. More Details.

Good luck and thank you for using FoodCoopShop!

If you have questions, first check existing github support issues