This is the installation guide for using the software “as is”. If you want to contribute to this project, please follow the developers installation in the project’s README.md.
If you have questions please drop Mario an email: firstname.lastname@example.org
If you want to update your installation to another version, please read the migration guide.
- Server connected to internet with shell access and cronjobs
- Apache with
- PHP => 7.2
- MySQL 5.7 (5.6 works too, but support can be stopped any time)
- A domain name registered for you
- Basic understanding of Apache Webserver, MySQL Database and Linux Server administration
- If you cloned the repository from Github: Node.js, npm and Composer
- PHP needs to be able to call mysqldump with exec() for database backups
That’s too much in depths for you? Look at this offer (German only) or drop Mario an email: email@example.com
Upload latest version to your server
The latest stable version is available at https://www.foodcoopshop.com/download. Do not clone from Git, you will get an unstable develop version! If you are a developer, please do clone the repository and don’t forget to change app.debug to true in your custom_config.php.
Download and unpack the ZIP file. Upload the content of the versioned folder to your server (e.g. using FTP). The destination folder must be accessible to your Apache Server, but not the Document Root (e.g. /var/www/foodcoopshop). Set the file access rights so that the Apache user (e.g. www-data) owns all files and folders:
me@home:/var/www$ sudo chown -R www-data:www-data foodcoopshop
Document Root / Virtual Host
If you develop on your local machine, your virtual host should end with “.test” (e.g. foodcoopshop.test). Then development environment and correct debug mode are set automatically. Simply add the prefered hostname to your local hosts file (e.g. /etc/hosts). Check in your browser by loading http://foodcoopshop.test/.
Create a new virtual host in your Apache configuration. Most common is copying /etc/apache2/sites-available/000-default.conf to 020-foodcoopshop.conf and symlinking it to /etc/apache2/sites-enabled:
me@home:/etc/apache2/sites-available$ sudo cp 000-default.conf 020-foodcoopshop.conf me@home:/etc/apache2/sites-available$ sudo ln -sr 020-foodcoopshop.conf ../sites-enabled
Now use your favourite editor to edit the new config file 020-foodcoopshop.conf (you must have root rights to edit):
- In the first line, set
<VirtualHost *:80>to your domain (e.g.
ServerAdminto a local mail account (e.g. root@localhost)
DocumentRootto /path/to/webroot (e.g. /var/www/foodcoopshop/webroot)
- Add a
<Directory>section to allow public access and make .htaccess work:
<Directory /var/www/foodcoopshop/webroot> Options FollowSymLinks MultiViews AllowOverride All Order allow,deny allow from all </Directory>
Then restart the webserver:
me@home:/etc/apache2/sites-available$ sudo service apache2 restart
$ cd /var/www/foodcoopshop/ $ chmod -R a+w ./files_private $ chmod -R a+w ./tmp $ chmod -R a+w ./webroot/cache $ chmod -R a+w ./webroot/files $ chmod -R a+w ./webroot/tmp
- Copy custom_config.default.php to custom_config.php and change your configuration if you want to
cakeServerNameto your server’s data https://yourdomain.tld (e.g. https://www.yourfoodcoop.com). Using https is recommended.
- The default configuration is found in app_config.php.
- Some configuration is stored in the database and can easily be changed from the admin screen: https://yourdomain.tld/admin/configurations (Super Admin account required)
- More configuration information in German and English
- Create a new database (e.g. foodcoopshop_db) and a new user (e.g. fcs_db_user) using the
mysqlcommandline tool. Refer to
man mysqland the online manual. Grant all rights on the new database to the new user. Note: In SQL terms the database is called scheme, so actually you create a new scheme and grant scheme rights.
- Define your database configuration in custom_config.php
- At first, import the initial database structure
- Then import initial database data in German, English or Polish. You can’t easily change the language after the installation, so please don’t play around.
- You can use the commandline or a webbased tool like Adminer or phpMyAdmin.
- Copy credentials.default.php to credentials.php and change the configuration
- The valid Super Admin account will be created later
- The email error logging can be enabled to ease server monitoring
- Be aware that you need to set
'EmailTransport' => [...]three times. Twice in
credentials.phpand once in
custom_config.php. There must be an EmailTransport config-block for the keys “default”, “debug” and “fallback”, so the configs must not stay commented!
Testing your email configuration
- Once you created a Super Admin account (will be created later), You can test your email configuration by accessing https://yourdomain.tld/admin/configurations/sendTestEmail in your browser.
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.
- Don’t forget to add the Super Admin data to credentials.php.
- Be aware: The Urls in this section depend on your installation language and therefore may be different for you. The Urls are constructed from translation-settings which can be found in the “/src/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
To enable all cronjobs, please read the cronjobs documentation.