Installation guide
- If you want to contribute to this project, please follow the contribution guideline.
- 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. Thank you!
Requirements
- Server connected to internet with shell access and cronjobs
- Apache webserver -
mod_rewrite
needs to be enabled! (Will also work on nginx, see below) - PHP => 8.0 (since v3.5 => PHP 8.1)
- PHP intl extension INTL_ICU_VERSION >= 50.1
- PHP ZipArchive class
- MySQL >= 5.7.7 (since v3.5 >= MySQL 8.0)
- A domain or subdomain
- Basic understanding of Webservers, MySQL Database and Linux Server administration
- If you cloned the repository from Github: Node.js, npm >= v7 and Composer v2
- PHP needs to be able to call mysqldump with exec() for database backups
There is an offer for paid support and hosting (in German) 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. New translations are welcome!
1) Setting up your 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.
2) 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.
- Set the document root to /your-folder/foodcoopshop/webroot. 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
Apache Webserver
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.<VirtualHost www.yourfoodcoop.com:80>
) - Set
ServerAdmin
to a local mail account (e.g. root@localhost) - Set
DocumentRoot
to /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
Nginx Webserver
Nginx webserver doesnât have something like mod_rewrite or .htaccess. See https://book.cakephp.org/2/en/installation/url-rewriting.html for details of preparing nginx to run cakephp-apps. The virtualhosts are configured in a similar manner under /etc/nginx/sites-avaliabe/xx symlinked to /etc/nginx/sites-enabled/xx and this would be a basic working virtualhost-sample for nginx with php7-fpm
server {
listen 80;
server_name your-foodcoops-hostname.net;
root /var/www/your-foodcoops-hostname.net/webroot/;
index index.php;
access_log /var/www/your-foodcoops-hostname.net/logs/access.log;
error_log /var/www/your-foodcoops-hostname.net/logs/error.log;
location / {
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass unix:/var/run/php/php7.3-fpm.sock;
include /etc/nginx/fastcgi_params;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}
Setting permissions
$ 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
Configuring FoodCoopShop
- Copy custom_config.default.php to custom_config.php and change your configuration if you want to
- Important for receiving correct links in emails: Set
cakeServerName
to 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
Database Setup
- Create a new database (e.g. foodcoopshop_db) and a new user (e.g. fcs_db_user) using the
mysql
commandline tool. Refer toman mysql
and 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 or English. You canât easily change the language after the installation.
- You can use the commandline or a webbased tool like Adminer or phpMyAdmin.
Credentials
- Copy credentials.default.php to credentials.php and change the configuration
- Only until v3.1: 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' => [...]
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
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.
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.
- Only until v3.1: 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 â/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
Cronjobs
To enable all cronjobs, read the cronjobs documentation.
Unit Tests
- If you want to contribute source code, all unit tests should pass locally before pushing:
- Create second database and add test database configuration to database.php. For details read Cakeâs testing documentation
- Import this dump into your test database
$ vendor/bin/phpunit
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 have questions, first check existing github support issues
- I#519, I#509, I#466
- If you still have questions, create a new issue.