.. | ||
.vscode | ||
README.md |
Getting Started
Prerequisites
In order to start deveping you need to satisfy the folowing prerequisites:
- Docker
- docker-compose
- user added to docker group
It is recommended you allocate at least 4GB of RAM to docker:
Bootstrap Containers for development
Clone and change directory to frappe_docker directory
git clone https://github.com/frappe/frappe_docker.git
cd frappe_docker
Use VSCode Remote Containers extension
For most people getting started with Frappe development, the best solution is to use VSCode Remote - Containers extension.
VSCode should automatically inquiry you to install the required extensions, that can also be installed manually as follows:
- Install Remote - Containers for VSCode
- through command line
code --install-extension ms-vscode-remote.remote-containers
- clicking on the button at the following link: Remote - Containers
- searching for extension
ms-vscode-remote.remote-containers
- through command line
- Install Python for VSCode
- through command line
code --install-extension ms-python.python
- clicking on the button at the following link: install
- searching for extension
ms-python.python
- through command line
After the extensions are installed, you can:
- Open frappe_docker folder in VS Code.
code .
- Launch the command, from Command Palette (Ctrl + Shift + P)
Execute Remote Containers : Reopen in Container
. You can also click in the bottom left corner to access the remote container menu.
Notes:
- The
development
directory is ignored by git. It is mounted and available inside the container. Create all your benches (installations of bench, the tool that manages frappe) inside this directory. - nvm with node v12 and v10 is installed. Check with
nvm ls
. Node v12 is used by default.
Setup first bench
Run the following commands in the terminal inside the container. You might need to create a new terminal in VSCode.
bench init --skip-redis-config-generation --frappe-branch version-12 frappe-bench
cd frappe-bench
Setup hosts
We need to tell bench to use the right containers instead of localhost. Run the following commands inside the container:
bench set-mariadb-host mariadb
bench set-redis-cache-host redis-cache:6379
bench set-redis-queue-host redis-queue:6379
bench set-redis-socketio-host redis-socketio:6379
Edit Honcho's Procfile
Honcho is the tool used by Bench to manage all the processes Frappe requires. Usually, these all run in localhost, but in this case, we have external containers for Redis. For this reason, we have to stop Honcho from trying to start Redis processes.
Open the Procfile file and remove the three lines containing the configuration from Redis, either by editing manually the file:
code Procfile
Or running the following command:
sed -i '/redis/d' ./Procfile
Create a new site with bench
Your installation already includes a site for localhost You can create a new site with the following command:
bench new-site sitename
for example:
bench new-site mysite.localhost
The command will ask the MariaDB root password. The default root password is 123
.
This will create a new site and a mysite.localhost
directory under frappe-bench/sites
.
You may need to configure your system /etc/hosts if you're on Linux, Mac, or its Windows equivalent.
Launching
To launch witho
bench new-site mysite.localhost
Your website will now be accessible on localhost on port 8000
Set bench developer mode on the new site
To develop a new app, the last step will be setting the site into developer mode. Documentation is available at this link.
bench --site my.site set-config developer_mode 1
bench --site my.site clear-cache
Install an app
To install an app we need to fetch it from the appropriate git repo, then install in on the appropriate site:
You can check VSCode container remote extension documentation regarding git creedential sharing.
bench get-app myapp https://github.com/myusername/myapp.git
bench --site my.site install-app myapp
Start Frappe without debugging
Execute following command from the frappe-bench
directory.
bench start
You can now login with user Administrator
and the password you choose when creating the site.
Note: To start bench with debugger refer section for debugging.
Fixing MariaDB issues after rebuilding the container
The bench new-site
command creates a user in MariaDB with container IP as host, for this reason after rebuilding the container there is a chance that you will not be able to access MariaDB correctly with the previous configuration
The parameter 'db_name'@'%'
needs to be set in MariaDB and permission to the site database suitably assigned to the user.
This step has to be repeated for all sites available under the current bench.
Example shows the queries to be executed for site localhost
Open sites/localhost/site_config.json:
code sites/localhost/site_config.json
and take note of the parameters db_name
and db_password
.
Enter MariaDB Interactive shell:
mysql -uroot -p123 -hmariadb
Execute following queries replacing db_name
and db_password
with the values found in site_config.json.
UPDATE mysql.user SET Host = '%' where User = 'db_name'; FLUSH PRIVILEGES;
SET PASSWORD FOR 'db_name'@'%' = PASSWORD('db_password'); FLUSH PRIVILEGES;
GRANT ALL PRIVILEGES ON `db_name`.* TO 'db_name'@'%'; FLUSH PRIVILEGES;
EXIT;
Manually start containers
In case you don't use VSCode, you may start the containers manually with the following command:
docker-compose -f .devcontainer/docker-compose.yml up -d
And enter the interactive shell for the development container with the following command:
docker exec -e "TERM=xterm-256color" -w /workspace/development -it devcontainer_frappe_1 bash
Start Frappe with Visual Studio Code Python Debugging
To enable Python debugging inside Visual Studio Code, you must first install the ms-python.python
extension inside the container.
- Click on the extension icon inside VSCode
- Search
ms-python.python
- Click on
Install on Dev Container: Frappe Bench
- Click on 'Reload'
We need to start bench separately through the VSCode debugger. For this reason, instead of running bench start
you should run the following command inside the frappe-bench directory:
honcho start \
socketio \
watch \
schedule \
worker_short \
worker_long \
worker_default
This command starts all processes with the exception of Redis (which is already running in separate container) and the web
process. The latter can can finally be started from the debugger tab of VSCode by clicking on the "play" button.
You can now login with user Administrator
and the password you choose when creating the site.
Developing using the interactive console
You can launch a simple interactive shell console in the terminal with:
bench console
More likely, you may want to launch VSCoode interactive console based on Jupyter kernel.
Launch VSCode command palette (cmd+shift+p or ctrl+shift+p), run the command Python: Select interpreter to start Jupyter server
and select /workspace/development/frappe-bench/env/bin/python
.
Then, run the commmand Python: Show Python interactive windows
from the VSCode command palette.
Replace my.site
with your site and run the following code in a Jupyter cell:
import frappe
frappe.init(site='my.site', sites_path='/workspace/development/frappe-bench/sites')
frappe.connect()
frappe.local.lang = frappe.db.get_default('lang')
frappe.db.connect()