https://foodcoopshop.github.io/assets/js/3659bb3e.77a05a3a.js

1"use strict";(self.webpackChunktest=self.webpackChunktest||[]).push([[9326],{2604:(e,n,o)=>{o.r(n),o.d(n,{assets:()=>a,contentTitle:()=>d,default:()=>h,frontMatter:()=>r,metadata:()=>s,toc:()=>l});const s=JSON.parse('{"id":"dev/installation-guide","title":"Installation guide","description":"* This installation guide always references to the latest stable version.","source":"@site/docs/dev/installation-guide.md","sourceDirName":"dev","slug":"/dev/installation-guide","permalink":"/dev/installation-guide","draft":false,"unlisted":false,"editUrl":"https://github.com/foodcoopshop/foodcoopshop.github.io/edit/main/docs/dev/installation-guide.md","tags":[],"version":"current","lastUpdatedAt":1772626064000,"frontMatter":{},"sidebar":"mySidebar","previous":{"title":"Rechtliches","permalink":"/rechtliches"},"next":{"title":"Migration guide","permalink":"/dev/migration-guide"}}');var i=o(4848),t=o(8453);const r={},d="Installation guide",a={},l=[{value:"Requirements",id:"requirements",level:2},{value:"Setting up your dev environment with Docker",id:"setting-up-your-dev-environment-with-docker",level:2},{value:"Using Docker for your production setup",id:"using-docker-for-your-production-setup",level:2},{value:"Installing the latest stable version for your live server",id:"installing-the-latest-stable-version-for-your-live-server",level:2},{value:"Setting permissions",id:"setting-permissions",level:2},{value:"Configuration",id:"configuration",level:2},{value:"Database Setup",id:"database-setup",level:2},{value:"Credentials",id:"credentials",level:2},{value:"Setting up cronjobs",id:"setting-up-cronjobs",level:2},{value:"Testing your email configuration",id:"testing-your-email-configuration",level:2},{value:"Setup security keys",id:"setup-security-keys",level:2},{value:"Create the valid Super Admin account",id:"create-the-valid-super-admin-account",level:2},{value:"Customizing CSS",id:"customizing-css",level:2},{value:"If you have questions, first check existing github support issues",id:"if-you-have-questions-first-check-existing-github-support-issues",level:2}];function c(e){const n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",header:"header",hr:"hr",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"installation-guide",children:"Installation guide"})}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["This installation guide always references to the ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/releases",children:"latest stable version"}),"."]}),"\n",(0,i.jsxs)(n.li,{children:["If you want to update your installation to another version, read the ",(0,i.jsx)(n.a,{href:"/dev/migration-guide",children:"migration guide"}),"."]}),"\n",(0,i.jsx)(n.li,{children:"You can help making this open source project more visible on GitHub by starring \u2b50 it."}),"\n"]})}),"\n",(0,i.jsx)(n.h2,{id:"requirements",children:"Requirements"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Server with ",(0,i.jsx)(n.strong,{children:"shell access"})," and ",(0,i.jsx)(n.strong,{children:"cronjobs"})]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"/dev/webserver-configuration",children:"Webserver - Nginx or Apache"})}),"\n",(0,i.jsx)(n.li,{children:"PHP >= 8.4.1"}),"\n",(0,i.jsx)(n.li,{children:"PHP intl extension INTL_ICU_VERSION >= 50.1"}),"\n",(0,i.jsx)(n.li,{children:"PHP Imagick and GD extension"}),"\n",(0,i.jsx)(n.li,{children:"PHP mbstring and curl"}),"\n",(0,i.jsx)(n.li,{children:"PHP bzip2 lib (for automatic database backups) (prior to v3.6: PHP ZipArchive class)"}),"\n",(0,i.jsx)(n.li,{children:"MySQL >= 8.0"}),"\n"]}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["There is an offer for ",(0,i.jsx)(n.a,{href:"https://www.foodcoopshop.com/das-angebot/",children:"paid support and hosting"})," if you don't want to spend your time on IT stuff."]}),"\n",(0,i.jsxs)(n.li,{children:["There are demo installations in ",(0,i.jsx)(n.a,{href:"https://demo-de.foodcoopshop.com/",children:"German"}),", ",(0,i.jsx)(n.a,{href:"https://demo-en.foodcoopshop.com/",children:"English"})," and ",(0,i.jsx)(n.a,{href:"https://demo-ru.foodcoopshop.com",children:"Russian"}),". Feel free to test before installing."]}),"\n"]})}),"\n",(0,i.jsx)(n.hr,{}

1),"\n",(0,i.jsx)(n.h2,{id:"setting-up-your-dev-environment-with-docker",children:(0,i.jsx)(n.a,{href:"/dev/docker-dev-environment",children:"Setting up your dev environment with Docker"})}),"\n",(0,i.jsx)(n.h2,{id:"using-docker-for-your-production-setup",children:"Using Docker for your production setup"}),"\n",(0,i.jsxs)(n.p,{children:["When you want to use Docker for your production instance take a look at the ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop-docker",children:"prod ready setup"})," and follow its manual. This also relieves you from a few of the following steps."]}),"\n",(0,i.jsx)(n.h2,{id:"installing-the-latest-stable-version-for-your-live-server",children:"Installing the latest stable version for your live server"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Download the latest stable version at ",(0,i.jsx)(n.a,{href:"https://www.foodcoopshop.com/download",children:"https://www.foodcoopshop.com/download"})," and upload the unpacked files to your server using FTP."]}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"/dev/webserver-configuration",children:"Webserver configuration"})}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"setting-permissions",children:"Setting permissions"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"bash ./devtools/installation/set-permissions.sh\n"})}),"\n",(0,i.jsx)(n.hr,{}),"\n",(0,i.jsx)(n.h2,{id:"configuration",children:"Configuration"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Copy ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/blob/main/config/custom_config.default.php",children:"custom_config.default.php"})," to custom_config.php and add your configuration overrides."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["The default configuration is found in ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/blob/main/config/app_config.php",children:"app_config.php"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Set ",(0,i.jsx)(n.code,{children:"App.fullBaseUrl"}),' to your server, e.g. "',(0,i.jsx)(n.a,{href:"https://yourdomain.tld",children:"https://yourdomain.tld"}),'" - NO TRAILING SLASH!']}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:["Some configuration is stored in the database and can easily be changed from the admin area: ",(0,i.jsx)(n.a,{href:"https://yourdomain.tld/admin/configurations",children:"https://yourdomain.tld/admin/configurations"})," (Super Admin account required)"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.a,{href:"/dev/configuration",children:"More infos"})}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"database-setup",children:"Database Setup"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Create a new database (e.g. foodcoopshop_db)"}),"\n",(0,i.jsx)(n.li,{children:"Define your database configuration in custom_config.php"}),"\n"]}),"\n",(0,i.jsx)(n.admonition,{type:"important",children:(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["run ",(0,i.jsx)(n.code,{children:"bash ./devtools/installation/init-database.sh de_DE"}),' (locales "en_US" and "ru_RU" are also supported)']}),"\n",(0,i.jsxs)(n.li,{children:["Import taxes for Austria: ",(0,i.jsx)(n.code,{children:"bash ./bin/cake seeds run AddTaxesAustriaSeed"})]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"OR"})," Import taxes for Germany: ",(0,i.jsx)(n.code,{children:"bash ./bin/cake seeds run AddTaxesGermanySeed"})]}),"\n"]})}),"\n",(0,i.jsx)(n.h2,{id:"credentials",children:"Credentials"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Copy ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/blob/main/config/credentials.default.php",children:"credentials.default.php"})," to credentials.php and change the configuration"]}),"\n",(0,i.jsx)(n.li,{children:"The email error logging can be enabled to ease server monitoring"}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.strong,{children:"Be aware"})," that you need to set ",(0,i.jsx)(n.code,{children:"'EmailTransport' => [...]"})," twice, once in ",(0,i.jsx)(n.code,{children:"credentials.php"})," and once in ",(0,i.jsx)(n.code,{children:"custom_config.php"}),'. There must be an EmailTransport config-block for the keys "default" and "debug" so the configs must not stay commented!']}),"\n",(0,i.jsxs)(n.li,{children:["See ",(0,i.jsx)(n.a,{href:"https://book.cakephp.org/4/en/core-libraries/email.html#configuring-transports",children:"https://book.cakephp.org/4/en/core-libraries/email.html#configuring-transports"})]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"setting-up-cronjobs",children:"Setting up cronjobs"}),"\n",(0,i.jsxs)(n.p,{children:["Follow the steps of the ",(0,i.jsx)(n.a,{href:"/dev/cronjobs",children:"cronjob documentation"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"testing-your-email-configuration",children:"Testing your email configuration"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Once you created a Super Admin account (instructions further down), You can test your email configuration by accessing ",(0,i.jsx)(n.a,{href:"https://yourdomain.tld/admin/configurations/sendTestEmail",children:"https://yourdomain.tld/admin/configurations/sendTestEmail"})," in your browser."]}

1),"\n",(0,i.jsxs)(n.li,{children:["As all emails are sent via the queue, be sure that you set it up correctly. See ",(0,i.jsx)(n.a,{href:"/dev/cronjobs",children:"cronjob documentation"}),"."]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"setup-security-keys",children:"Setup security keys"}),"\n",(0,i.jsxs)(n.p,{children:["Open your domain ",(0,i.jsx)(n.a,{href:"https://yourdomain.tld",children:"https://yourdomain.tld"})," in a browser and follow the steps shown to create secure values for the security salt ",(0,i.jsx)(n.code,{children:"Security.salt"}),". Set it in custom_config.php"]}),"\n",(0,i.jsx)(n.h2,{id:"create-the-valid-super-admin-account",children:"Create the valid Super Admin account"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Open ",(0,i.jsx)(n.a,{href:"https://yourdomain.tld/sign-in",children:"https://yourdomain.tld/sign-in"}),' in your browser and register with your personal email address (down below at "Create account")']}),"\n",(0,i.jsx)(n.li,{children:'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.'}),"\n",(0,i.jsxs)(n.li,{children:["Open ",(0,i.jsx)(n.a,{href:"https://yourdomain.tld/request-new-password",children:"https://yourdomain.tld/request-new-password"}),', type in your email address and press "Send".']}),"\n",(0,i.jsx)(n.li,{children:"With the password that was sent to you by email you are able to login as a Super Admin."}),"\n"]}),"\n",(0,i.jsxs)(n.admonition,{type:"info",children:[(0,i.jsx)(n.p,{children:'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":'}),(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Sign-in: ",(0,i.jsx)(n.a,{href:"https://yourdomain.tld/anmelden",children:"https://yourdomain.tld/anmelden"})]}),"\n",(0,i.jsxs)(n.li,{children:["Request-new-password: ",(0,i.jsx)(n.a,{href:"https://yourdomain.tld/neues-passwort-anfordern",children:"https://yourdomain.tld/neues-passwort-anfordern"})]}),"\n"]})]}),"\n",(0,i.jsx)(n.h2,{id:"customizing-css",children:"Customizing CSS"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["Change app.debug to ",(0,i.jsx)(n.code,{children:"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)."]}),"\n",(0,i.jsxs)(n.li,{children:["To re-build the assets in /cache for production, run ",(0,i.jsx)(n.code,{children:"composer build"})]}),"\n"]}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsxs)(n.p,{children:['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 ',(0,i.jsx)(n.a,{href:"https://github.com/cakephp/debug_kit",children:"https://github.com/cakephp/debug_kit"})," and copy it into the plugins folder. ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/issues/931",children:"More Details"}),"."]})}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsx)(n.p,{children:"Good luck and thank you for using FoodCoopShop!"})}),"\n",(0,i.jsx)(n.h2,{id:"if-you-have-questions-first-check-existing-github-support-issues",children:"If you have questions, first check existing github support issues"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/issues/519",children:"I#519"}),", ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/issues/509",children:"I#509"}),", ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/issues/466",children:"I#466"})]}),"\n",(0,i.jsxs)(n.li,{children:["If you still have questions, ",(0,i.jsx)(n.a,{href:"https://github.com/foodcoopshop/foodcoopshop/issues/new",children:"create a new issue"}),"."]}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},8453:(e,n,o)=>{o.d(n,{R:()=>r,x:()=>d});var s=o(6540);const i={},t=s.createContext(i);function r(e){const n=s.useContext(t);return s.useMemo((function(){return"function"==typeof e?e(n):{...n,...e}}),[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:r(e.components),s.createElement(t.Provider,{value:n},e.children)}}}]);