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
- Download the latest stable version at https://www.foodcoopshop.com/download and upload the unpacked files to your server using FTP.
- Webserver configuration
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 toApp.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
- At first, import the initial database structure
- Then import initial database data in German or English. You canât easily change the language after the installation.
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
- Copy credentials.default.php to credentials.php and change the configuration
- The email error logging can be enabled to ease server monitoring
- Be aware that you need to set
'EmailTransport' => [...]
twice, once incredentials.php
and once incustom_config.php
. There must be an EmailTransport config-block for the keys âdefaultâ and âdebugâ so the configs must not stay commented! - See https://book.cakephp.org/4/en/core-libraries/email.html#configuring-transports
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
- I#519, I#509, I#466
- If you still have questions, create a new issue.