Erp Single Server
ERP Single Server Example
In this use case we have a single server with a static IP attached to it. It can be used in scenarios where one powerful VM has multiple benches and applications or one entry level VM with single site. For single bench, single site setup follow only up to the point where first bench and first site is added. If you choose this setup you can only scale vertically. If you need to scale horizontally you’ll need to backup the sites and restore them on to cluster setup.
We will setup the following:
- Install docker and docker compose v2 on linux server.
- Install traefik service for internal load balancer and letsencrypt.
- Install MariaDB with containers.
- Setup project called
erpnext-one
and create sitesone.example.com
andtwo.example.com
in the project. - Setup project called
erpnext-two
and create sitesthree.example.com
andfour.example.com
in the project.
Explanation:
Single instance of Traefik will be installed and act as internal loadbalancer for multiple benches and sites hosted on the server. It can also load balance other applications along with frappe benches, e.g. wordpress, metabase, etc. We only expose the ports 80
and 443
once with this instance of traefik. Traefik will also take care of letsencrypt automation for all sites installed on the server. Why choose Traefik over Nginx Proxy Manager? Traefik doesn’t need additional DB service and can store certificates in a json file in a volume.
Single instance of MariaDB will be installed and act as database service for all the benches/projects installed on the server.
Each instance of ERPNext project (bench) will have its own redis, socketio, gunicorn, nginx, workers and scheduler. It will connect to internal MariaDB by connecting to MariaDB network. It will expose sites to public through Traefik by connecting to Traefik network.
Install Docker
Easiest way to install docker is to use the convenience script.
Note: The documentation assumes Ubuntu LTS server is used. Use any distribution as long as the docker convenience script works. If the convenience script doesn’t work, you’ll need to install docker manually.
Install Compose V2
Refer original documentation for updated version.
Prepare
Clone frappe_docker
repo for the needed YAMLs and change the current working director of you shell to the cloned repo.
Create configuration and resources directory
The ~/gitops
directory will store all the resources that we use for setup. We will also keep the environment files in this directory as there will be multiple projects with different environment variables. You can create a private repo for this directory and track the changes there.
Install Traefik
Basic Traefik setup using docker compose.
Create a file called traefik.env
in ~/gitops
Note:
- Change the domain from
traefik.example.com
to the one used in production. DNS entry needs to point to the Server IP. - Change the letsencrypt notification email from
admin@example.com
to correct email. - Change the password from
changeit
to more secure.
env file generated at location ~/gitops/traefik.env
will look like following:
Deploy the traefik container with letsencrypt SSL
This will make the traefik dashboard available on traefik.example.com
and all certificates will reside in /data/traefik/certificates
on host filesystem.
For LAN setup deploy the traefik container without overriding overrides/compose.traefik-ssl.yaml
.
Install MariaDB
Basic MariaDB setup using docker compose.
Create a file called mariadb.env
in ~/gitops
Note:
- Change the password from
changeit
to more secure.
env file generated at location ~/gitops/mariadb.env
will look like following:
Note: Change the password from changeit
to more secure one.
Deploy the mariadb container
This will make mariadb-database
service available under mariadb-network
. Data will reside in /data/mariadb
.
Install ERPNext
Create first bench
Create first bench called erpnext-one
with one.example.com
and two.example.com
Create a file called erpnext-one.env
in ~/gitops
Note:
- Change the password from
changeit
to the one set for MariaDB compose in the previous step.
env file is generated at location ~/gitops/erpnext-one.env
.
Create a yaml file called erpnext-one.yaml
in ~/gitops
directory:
For LAN setup do not override compose.multi-bench-ssl.yaml
.
Use the above command after any changes are made to erpnext-one.env
file to regenerate ~/gitops/erpnext-one.yaml
. e.g. after changing version to migrate the bench.
Load custom apps through json
In the frappe_docker/development
directory find the apps-example.json
file. Create a json file called apps.json
in ~/gitops
:
In the apps.json
file, add the names of the applications that you want to use in the production environment:
Generate base64 string stored in the APPS_JSON_BASE64
environment variable from json file:
Note:
url
needs to be http(s) git url with token/auth in case of private repo.- add dependencies manually in
apps.json
e.g. addpayments
if you are installingerpnext
- use fork repo or branch for ERPNext in case you need to use your fork or test a PR.
Build Image With Custom Apps
Execute next command from frappe_docker
directory:
Note:
FRAPPE_PATH
andFRAPPE_BRANCH
build args are optional and can be overridden in case of fork/branch or test a PR.- Make sure
APPS_JSON_BASE64
variable has correct base64 encoded JSON string. It is consumed as build arg, base64 encoding ensures it to be friendly with environment variables. Usejq empty apps.json
to validateapps.json
file. - Make sure the
-t
(tag) is valid image name that will be pushed to registry. See section below for remarks about its use. - Change
--build-arg
as per version of Python, NodeJS, Frappe Framework repo and branch .git
directories for all apps are removed from the image.
Push image to registry to use in yaml files
Login to docker
Push image
Use Custom Apps Images
On the compose.yaml replace the image reference to the tag
you used when you built it. Then, if you used a tag like custom_erpnext:staging
the x-customizable-image
section will look like this:
The pull_policy
above is optional and prevents docker
to try to download the image when that one has been built locally.
Make sure image name is correct to be pushed to registry. After the images are pushed, you can pull them to servers to be deployed. If the registry is private, additional auth is needed.
Deploy ERPNext Containers
Deploy erpnext-one
containers:
Create sites one.example.com
:
You can stop here and have a single bench single site setup complete. ERPNext will be available under your domain.
Install custom apps
Now you need to install the custom apps from backend container. Go to the backend container using:
Use bench install-app
command to install the custom apps:
You can stop here and have a single bench single site with custom apps setup complete.