How to Dockerize Frappe Applications

This article is intended for Frappe developers and DevOps engineers who are working on generating Docker images for their applications.

What is frappe framework?

Frappe Framework is an open-source, full-stack web application framework written in Python. It is specifically designed for rapid development of web applications, particularly ERP (Enterprise Resource Planning) systems, CRMs (Customer Relationship Management), and other business applications.

Features of frappe framework

1. python-based
2. full stack
3. Modular and extensible
4. ORM
5. Restful API
6. User Authentication and Permissions
7. Workflow management
8. UI Components and Templates

To learn more on how to get started with frappe framework use the below link:

Frappe Framework Tutorial

How to Dockerize

Dockerizing applications offers numerous benefits, including portability, scalability, simplified deployment processes, version control, adoption of microservices architecture, and easy setup of automated testing environments.

Below are steps to follow when dockerizing a frappe application:

1. Clone the frappe docker repository.

git clone https://github.com/frappe/frappe_docker

Why it is important to use the frappe docker repository:

• Base Image and Dependencies: The Frappe Docker repository provides a base Docker image with all the necessary dependencies and configurations required to run applications built on the Frappe Framework. This includes Python, Node.js, Redis, MariaDB (or MySQL), and other dependencies needed for Frappe-based applications.
• Standardized Environment: Using the Frappe Docker image ensures that your custom application is running in an environment that is consistent with the Frappe Framework. This helps in avoiding compatibility issues or unexpected behavior due to differences in environments between development and production.
• Ease of Setup: Dockerizing applications using the Frappe Docker repository simplifies the setup process. You don’t need to manually install and configure all the dependencies and services required by Frappe. Instead, you can use the pre-built Docker image, which saves time and effort.
• Version Compatibility: The Frappe Docker repository often provides images for specific versions of the Frappe Framework. This ensures that your custom application is using a compatible version of Frappe, reducing the risk of compatibility issues.
• Maintenance and Updates: When you dockerize your application using the Frappe Docker repository, you can easily update to newer versions of the Frappe Framework by pulling the updated Docker image. This simplifies maintenance and ensures that you have access to the latest features and security updates.
• Community Support: Using the Frappe Docker repository means you can benefit from the community support and contributions. If you encounter issues or need assistance, there is a community of Frappe developers who can provide guidance and help troubleshoot problems specific to the Dockerized Frappe environment

2. Switch to the frappe_docker directory

cd frappe_docker

3. Create an apps.json file at the root of the directory.

The file should include repository links to your Frappe applications. The example below includes links for ERPNext, Payments, and HRMS.

[
    {
      "url": "https://github.com/frappe/erpnext",
      "branch": "version-15"
    },
    {
      "url": "https://github.com/frappe/payments",
      "branch": "version-15"
    },
    {
      "url": "https://github.com/frappe/hrms",
      "branch": "version-15"
    }
]

NOTE: The repositories listed above are for public repositories, to use a private repository, use the below format:

[
    {
        "url": "https://{USERNAME}:{ACCESS_TOKENS}@github.com/{repo}.git",
        "branch": "{BRANCH_NAME}"
    },
    {
        "url": "https://{USERNAME}:{ACCESS_TOKENS}@github.com/{repo}.git",
        "branch": "{BRANCH_NAME}"
    },
    {
        "url": "https://{USERNAME}:{ACCESS_TOKENS}@github.com/{repo}.git",
        "branch": "{BRANCH_NAME}"
    }
]

In the above, replace the values in the curly braces with your own

USERNAME - github username

ACCESS_TOKENS - github personal access tokens. Check the below link to create personal access tokens in github:

Managing your personal access tokens - GitHub Docs

BRANCH_NAME -This refers to the name of the branch where your code is currently located. It could be the “master” branch or “dev” branch.

4. Generate base64 string from the apps.json file you created above using the command below:

export APPS_JSON_BASE64=$(base64 -w 0 apps.json)

You can echo to see if it worked:

echo $APPS_JSON_BASE64

5. Build the docker image.

Note that you can adjust the Python and Node versions in the command below to match the versions used to create your application. In the example below, we will use the latest versions because we are creating an image for ERPNext, Payments, and HRMS, which are in the latest version.

You can customize the Docker tag to your preferred naming convention. In the example below, we will tag the image as “first_image”:

NOTE: Please ensure you run the following command in the root directory of frappe_docker to avoid any errors:

You must install docker to execute the below command. You can also choose to use buildah.

docker build \
  --build-arg=FRAPPE_PATH=https://github.com/frappe/frappe \
  --build-arg=FRAPPE_BRANCH=version-15 \
  --build-arg=PYTHON_VERSION=3.11.6 \
  --build-arg=NODE_VERSION=18.18.2 \
  --build-arg=APPS_JSON_BASE64=$APPS_JSON_BASE64 \
  --tag=first_image \
  --file=images/custom/Containerfile .

After executing the command above, the image creation process should begin, as shown below:

The docker image creation process may take a few minutes. Please wait for it to complete.

After the image creation is completed, you can run the following commands to check if the image was created correctly and contains all your applications:

# List all the images, you should see first_image in the list
docker images

# Run the docker image in the background using the -d tag
docker run -d first_image

# List running images to get the container id of our image
docker ps

# exec into the container to check if all apps are in the image
docker exec -it {CONTAINER_ID} /bin/bash

To verify if all apps are present in the newly created image, use the following command while inside the container:

cd apps
ls

The ls command should list all the apps in the image, in our case you should see the below apps:

all apps in the docker image

If you see your apps listed in the container, congratulations! 🎊 You have successfully created an image for your Frappe application. 👏

Debugging

If you do not find any of the apps in your container, please revisit the apps.json file to ensure that all the apps were listed correctly. Sometimes, the issue might be due to incorrect tokens provided or the username, which can result in the image creation failing because it cannot access the GitHub repository.

What are the next steps?

The next steps involve deploying to Kubernetes to host your Frappe application. Stay tuned for the next article where we will cover this process in detail.