accounting/bench
2
0
Fork 0
mirror of https://github.com/frappe/bench.git synced 2024-09-22 12:09:02 +00:00
Code Issues Releases Activity

Merge pull request #901 from gavindsouza/bench-docs-refact

Browse Source 
chore: updated Bench docs
This commit is contained in:
gavin 2020-01-20 10:41:47 +05:30 committed by GitHub
commit fe94787f8c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 442 additions and 279 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
.github/ISSUE_TEMPLATE/bug-report.md vendored Normal file
View File

@ -0,0 +1,47 @@
---
name: Bug report
about: Report a bug encountered while using bench
labels: bug
---
Issue: Bug report
**Do the checklist before filing an issue:**
- [ ] Can you replicate the issue?
- [ ] Is this something you can debug and fix? Send a pull request! Bug fixes and documentation fixes are welcome
**Describe the bug** :chart_with_downwards_trend:
A clear and concise description of what the bug is.
**To Reproduce** :page_with_curl:
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
**Expected behavior** :chart_with_upwards_trend:
A clear and concise description of what you expected to happen.
**Screenshots** :crystal_ball:
If applicable, add screenshots to help explain your problem.
**OS (please complete the following information):** :cyclone:
- [ ] Linux: `distro:version`
- [ ] macOS: `version`
- [ ] Windows `version`
- [ ] Others? `haros:distro:version`
**Version Information**
Can be found out by running `bench version` in your respective bench folder
- Bench Branch: `master` _(Only master is supported)_
- Frappe Version:
- ERPNext Version:
**Additional context** :page_facing_up:
Add any other context about the problem here.
**Possible Solution** :bookmark_tabs:
Any idea what might be causing the issue. Or if you have a proposed solution to the problem.

68
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -1,68 +0,0 @@
---
name: Bug report
about: Create a report to help us improve
---
Issue: Bug report
Our project, as you've probably heard, is getting really popular and truth is we're getting a bit overwhelmed by the activity surrounding it. There are just too many issues for us to manage properly.
**Do the checklist before filing an issue:**
- [ ] Have a usage question? Ask your question on [Discuss Forum](https://discuss.erpnext.com). We use [Discuss Forum](https://discuss.erpnext.com) for usage question and GitHub for bugs.
- [ ] Can you replicate the issue?
- [ ] Is this something you can debug and fix? Send a pull request! Bug fixes and documentation fixes are welcome
**Describe the bug** :chart_with_downwards_trend:
A clear and concise description of what the bug is.
**To Reproduce** :page_with_curl:
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
**Expected behavior** :chart_with_upwards_trend:
A clear and concise description of what you expected to happen.
**Screenshots** :crystal_ball:
If applicable, add screenshots to help explain your problem.
**Desktop (please complete the following information):** :cyclone:
- OS:
- [ ] Linux
- [ ] macOS
- [ ] Windows
- [ ] Others? Please mention:
- Browser:
- [ ] Safari
- [ ] Chrome
- [ ] Firefox
- [ ] Other? Please mention:
**Smartphone (please complete the following information):** :iphone: :computer:
- Device:
- [ ] iPhone
- [ ] Android
- Browser:
- [ ] Safari
- [ ] Chrome
- [ ] Firefox
- [ ] Other? Please mention:
**Version Information**
- Which branch are you on?
- [ ] `master` :star2:
- [ ] `develop` :fire:
- Frappe Version:
- ERPNext Version:
**Additional context** :page_facing_up:
Add any other context about the problem here.
**Possible Solution** :bookmark_tabs:
Any idea what might be causing the issue. Or if you have a proposed solution to the problem,
**Please don't be intimidated by the long list of options you've fill. Try to fill out as much as you can. Remember, the more the information the easier it is for us to replicate and fix the issue** :grin:

43
.github/ISSUE_TEMPLATE/easy-install.md vendored Normal file
View File

@ -0,0 +1,43 @@
---
name: Easy Install
about: Report a issue encountered or a suggestion for improving experience while using easy install to setup a "Bench + Frappe + ERPNext" environment
labels: easy-install
---
Issue: Easy Install
**Do the checklist before filing an issue:**
- [ ] Did you retain the logfile (path of logfile is shared while the script is run)? We definitely **need** the logfile to debug any easy install related issues.
- [ ] Is this something you can debug and fix? Send a pull request! Bug fixes and documentation fixes are welcome
**Distro Information (Required)**
<!--
Paste the contents of
1. uname -a
2. cat /etc/*-release
-->
**Command Run (Required)**
<!--
Knowing what was the exact command run ie which flags were used will help us narrow down the exact cause for the failure and put in a fix soon
-->
**Log File (Required)**
<!--
Upload the logfile and share the link for the same or just paste it directly (hopefully the last 50 lines should do)
-->
**Screenshots**
<!--
Optional: Screenshot of the runtime of the script
-->
**Additional context**
<!--
We need all the information we can get our hands on
-->
**Possible Solution**
<!--
Any idea what might be causing the issue. Or if you have a proposed solution to the problem?
-->

2
.github/ISSUE_TEMPLATE/feature_request.md → .github/ISSUE_TEMPLATE/feature-request.md vendored
View File

@ -1,7 +1,7 @@
--- ---
name: Feature request name: Feature request
about: Suggest an idea for this project about: Suggest an idea for this project
label: feature-request
--- ---
Issue: Feature Request Issue: Feature Request

19
.github/ISSUE_TEMPLATE/questions-about-using-bench.md vendored Normal file
View File

@ -0,0 +1,19 @@
---
name: Question about using Bench/Frappe/Frappe Apps
about: This is not the appropriate channel
labels: invalid
---
Please post on our forums:
for questions about using `bench`, probably the best place to start is the [bench repo](https://github.com/frappe/bench) or [bench intro](https://frappe.io/bench) or [bench docs](https://frappe.io/docs/bench)
for questions about using the `Frappe Framework`: ~~https://discuss.frappe.io~~ => [stackoverflow](https://stackoverflow.com/questions/tagged/frappe) tagged under `frappe`
for questions about using `ERPNext`: https://discuss.erpnext.com
For documentation issues, use the [Frappe Framework Documentation](https://frappe.io/docs/user/en) or the [developer cheetsheet](https://github.com/frappe/frappe/wiki/Developer-Cheatsheet)
For a slightly outdated yet informative developer guide: https://www.youtube.com/playlist?list=PL3lFfCEoMxvzHtsZHFJ4T3n5yMM3nGJ1W
> **Posts that are not bug reports or feature requests will not be addressed on this issue tracker.**

53
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -1,4 +1,39 @@
Pull-Request <!--
Some key notes before you open a PR:
1. Select which branch should this PR be merged in?
2. PR name follows [convention](http://karma-runner.github.io/4.0/dev/git-commit-msg.html)
3. Update necessary Documentation
4. Put `closes #XXXX` in your comment to auto-close the issue that your PR fixes
Also, if you're new here
- Documentation Guidelines => https://github.com/frappe/erpnext/wiki/Updating-Documentation
- Contribution Guide => https://github.com/frappe/bench/blob/master/docs/contribution_guidelines.md
- Pull Request Checklist => https://github.com/frappe/erpnext/wiki/Pull-Request-Checklist
-->
What type of a PR is this?
- [ ] Changes to Existing Features
- [ ] New Feature Submissions
- [ ] Bug Fix
- [ ] Breaking Change (include change in API behaviours, etc.)
---
> Please provide enough information so that others can review your pull request:
<!-- You can skip this if you're fixing a typo or updating existing documentation -->
---
> Explain the **details** for making this change. What existing problem does the pull request solve? The following checklist could help
- [ ] Have you followed the guidelines in our Contributing document? - [ ] Have you followed the guidelines in our Contributing document?
- [ ] Have you checked to ensure there aren't other open [Pull Requests](../pulls) for the same update/change? - [ ] Have you checked to ensure there aren't other open [Pull Requests](../pulls) for the same update/change?
@ -11,18 +46,8 @@ Pull-Request
--- ---
What type of a PR is this? <!-- Example: When "Adding a function to do X", explain why it is necessary to have a way to do X. -->
- [ ] Changes to Existing Features > Screenshots/GIFs
- [ ] New Feature Submissions
- [ ] Bug Fix
- [ ] Breaking Change
---
- Motivation and Context (What existing problem does the pull request solve):
- Related Issue:
- Screenshots (if applicable, remember, a picture tells a thousand words):
**Please don't be intimidated by the long list of options you've fill. Try to fill out as much as you can. Remember, the more the information the easier it is for us to test and get your pull request merged** :grin:
<!-- Add images/recordings to better visualize the change: expected/current behviour -->

287
README.md
View File

@ -1,102 +1,79 @@
<div align="center"> <div align="center">
<img src="https://github.com/frappe/design/raw/master/logos/png/bench-logo.png" height="128"> <img src="https://github.com/frappe/design/raw/master/logos/png/bench-logo.png" height="128">
<h2>Frappe Bench</h2> <h2>bench</h2>
</div> </div>
bench is a command-line utility that helps you to install apps, manage multiple sites and update Frappe / ERPNext apps on */nix (macOS, Ubuntu, Debian, CentOS, etc) for development and production.
The bench is a command-line utility that helps you to install apps, manage multiple sites and update Frappe / ERPNext apps on */nix (Ubuntu, Debian, CentOS, etc) for development and production. Bench will also create nginx and supervisor config files, setup backups and much more.
If you are using on a VPS make sure it has >= 1Gb of RAM or has swap setup properly.
To do this install, you must have basic information on how Linux works and should be able to use the command-line. If you are looking easier ways to get started and evaluate ERPNext, [download the Virtual Machine](https://erpnext.com/download) or take [a free trial on erpnext.com](https://erpnext.com/pricing).
If you have questions, please ask them on the [forum](https://discuss.erpnext.com/).
## Installation
### Installation Requirements
You will need a computer/server. Options include:
- A Normal Computer/VPS/Baremetal Server: This is strongly recommended. Frappe/ERPNext installs properly and works well on these
- A Raspberry Pi, SAN Appliance, Network Router, Gaming Console, etc.: Although you may be able to install Frappe/ERPNext on specialized hardware, it is unlikely to work well and will be difficult for us to support. Strongly consider using a normal computer/VPS/baremetal server instead. **We do not support specialized hardware**.
- A Toaster, Car, Firearm, Thermostat, etc.: Yes, many modern devices now have embedded computing capability. We live in interesting times. However, you should not install Frappe/ERPNext on these devices. Instead, install it on a normal computer/VPS/baremetal server. **We do not support installing on noncomputing devices**.
To install the Frappe/ERPNext server software, you will need an operating system on your normal computer which is not Windows. Note that the command line interface does work on Windows, and you can use Frappe/ERPNext from any operating system with a web browser. However, the server software does not run on Windows. It does run on other operating systems, so choose one of these instead:
- Linux: Ubuntu, Debian, CentOS are the preferred distros and are tested. [Arch Linux](https://github.com/frappe/bench/wiki/Install-ERPNext-on-ArchLinux) can also be used
- Mac OS X
### Manual Install
To manually install frappe/erpnext, you can follow this [this wiki](https://github.com/frappe/frappe/wiki/The-Hitchhiker%27s-Guide-to-Installing-Frappe-on-Linux) for Linux and [this wiki](https://github.com/frappe/frappe/wiki/The-Hitchhiker's-Guide-to-Installing-Frappe-on-Mac-OS-X) for MacOS. It gives an excellent explanation about the stack. You can also follow the steps mentioned below:
#### 1. Install Pre-requisites
<pre>
• Python 3.6+
• Node.js 12
• Redis 5 (caching and realtime updates)
• MariaDB 10.3 / Postgres 9.5 (to run database driven apps)
• yarn 1.12+ (js dependency manager)
• pip 15+ (py dependency manager)
• cron (scheduled jobs)
• wkhtmltopdf (version 0.12.5 with patched qt) (for pdf generation)
• Nginx (for production)
</pre>
#### 2. Install Bench
Install bench as a *non root* user,
git clone https://github.com/frappe/bench ~/.bench
pip install --user -e ~/.bench
Note: Please do not remove the bench directory the above commands will create
#### Basic Usage
* Create a new bench
The init command will create a bench directory with frappe framework
installed. It will be setup for periodic backups and auto updates once
a day.
bench init frappe-bench && cd frappe-bench
* Add a site
Frappe apps are run by frappe sites and you will have to create at least one
site. The new-site command allows you to do that.
bench new-site site1.local
* Add apps
The get-app command gets remote frappe apps from a remote git repository and installs them. Example: [erpnext](https://github.com/frappe/erpnext)
bench get-app erpnext https://github.com/frappe/erpnext
* Install apps
To install an app on your new site, use the bench `install-app` command.
bench --site site1.local install-app erpnext
* Start bench
To start using the bench, use the `bench start` command
bench start
To login to Frappe / ERPNext, open your browser and go to `[your-external-ip]:8000`, probably `localhost:8000`
The default username is "Administrator" and password is what you set when you created the new site.
> **Note**: If you are looking for easier ways to get started and evaluate ERPNext, [download the Virtual Machine](https://erpnext.com/download) or take [a free trial on erpnext.com](https://erpnext.com/pricing).
--- ---
## Easy Install # Table of Contents
- [bench CLI](#bench-cli)
- [Usage](#usage)
- [Installation](#installation)
- [Easy Install Script](#easy-install-script)
- [Release Bench](#release-bench)
- [Guides](#guides)
- [Resources](#resources)
- [License](#license)
---
# bench CLI
Bench is a command line tool that helps you install, setup, manage multiple sites and apps based on Frappe Framework.
---
## Usage
* Create a new bench
bench init [bench-name]
* Add a site under current bench
bench new-site [site-name]
* Add apps to bench
bench get-app [app-name] [app-link]
* Install apps on a particular site
bench --site [site-name] install-app [app-name]
* Start bench (only for development)
bench start
* Show bench help
bench --help
_Note:_ Apart from `bench init`, all other bench commands have to be run having the respective bench directory as the working directory. _(`bench update` may also be run, but it's behaviour is covered in depth in the docs)_
For more in depth information on commands and usage follow [here](https://github.com/frappe/bench/blob/master/docs/commands_and_usage.md).
---
## Installation
To do this install, you must have basic information on how Linux works and should be able to use the command-line. bench will also create nginx and supervisor config files, setup backups and much more. If you are using on a VPS make sure it has >= 1Gb of RAM or has swap setup properly.
git clone https://github.com/frappe/bench ~/.bench
pip3 install --user -e ~/.bench
As bench is a python application, its installation really depends on `python` + `pip` + `git`. The Frappe Framework, however has various other system dependencies like `nodejs`, `yarn`, `redis` and a database system like `mariadb` or `postgres`. Go through the [installation requirements](https://github.com/frappe/bench/blob/master/docs/installation.md) for an updated list.
If you have questions, please ask them on the [forum](https://discuss.erpnext.com/c/bench) under the "Install / Update" category.
---
# Easy Install Script
- This is an opinionated setup so it is best to setup on a blank server. - This is an opinionated setup so it is best to setup on a blank server.
- Works on Ubuntu 16.04+, CentOS 7+, Debian 8+ - Works on Ubuntu 16.04+, CentOS 7+, Debian 8+
@ -106,124 +83,40 @@ Note: Please do not remove the bench directory the above commands will create
- MariaDB (root) password may be `password` on a fresh server - MariaDB (root) password may be `password` on a fresh server
- You can then login as **Administrator** with the Administrator password - You can then login as **Administrator** with the Administrator password
- The log file is saved under `/tmp/logs/install_bench.log` in case you run into any issues during the install. - The log file is saved under `/tmp/logs/install_bench.log` in case you run into any issues during the install.
- If you find any problems, post them on the forum: [https://discuss.erpnext.com](https://discuss.erpnext.com) - If you find any problems, post them on the forum: [https://discuss.erpnext.com](https://discuss.erpnext.com/c/bench) with the `installation_problem` under "Install / Update" category.
Open your Terminal and enter: wget https://raw.githubusercontent.com/frappe/bench/master/playbooks/install.py
python3 install.py --production
#### 0. Setup user & Download the install script Follow [Easy Install Docs](https://github.com/frappe/bench/blob/master/docs/easy_install.md) for more information.
If you are on a fresh server and logged in as root, at first create a dedicated user for frappe
& equip this user with sudo privileges
```
adduser [frappe-user]
usermod -aG sudo [frappe-user]
```
*(it is very common to use "frappe" as frappe-username, but this comes with the security flaw of ["frappe" ranking very high](https://www.reddit.com/r/dataisbeautiful/comments/b3sirt/i_deployed_over_a_dozen_cyber_honeypots_all_over/?st=JTJ0SC0Q&sh=76e05240) in as a username challenged in hacking attempts. So, for production sites it is highly recommended to use a custom username harder to guess)*
Switch to `[frappe-user]` (using `su [frappe-user]`) and start the setup
wget https://raw.githubusercontent.com/frappe/bench/master/playbooks/install.py
#### 1. Run the install script
sudo python3 install.py
*Note: `user` flag to create a user and install using that user (By default, the script will create a user with the username `frappe` if the --user flag is not used)*
For production or development, append teh `--production` or `--develop` flag to the command respectively.
sudo python3 install.py --production --user [frappe-user]
or
sudo python3 install.py --develop
sudo python3 install.py --develop --user [frappe-user]
sudo python3 install.py --production --user [frappe-user] --container
*Note: `container` flag to install inside a container (this will prevent the `/proc/sys/vm/swappiness: Read-only` file system error)*
python3 install.py --production --version 11 --user [frappe-user]
use --version flag to install specific version
python3 install.py --production --version 11 --python python2.7 --user [frappe-user]
use --python flag to specify virtual environments python version, by default script setup python3
#### What will this script do?
- Install all the pre-requisites
- Install the command line `bench` (under ~/.bench)
- Create a new bench (a folder that will contain your entire frappe/erpnext setup at ~/frappe-bench)
- Create a new ERPNext site on the bench (site1.local)
#### How do I start ERPNext
1. For development: Go to your bench folder (`frappe-bench` by default) and start the bench with `bench start`
2. For production: Your process will be setup and managed by `nginx` and `supervisor`. [Setup Production](https://frappe.io/docs/user/en/bench/guides/setup-production.html)
--- ---
# Release Bench
## Bench Manager (GUI for Bench) Releases can be made for [Frappe](https://github.com/frappe/frappe) apps using bench. More information about this process can be found [here](https://github.com/frappe/bench/blob/master/docs/releasing_frappe_apps.md).
Bench Manager is a graphical user interface to emulate the functionalities of Frappe Bench. Like the command line utility it helps you install apps, manage multiple sites, update apps and much more. ---
### Installation # Bench Manager (GUI for Bench)
``` [Bench Manager](https://github.com/frappe/bench_manager) is a graphical user interface to emulate the functionalities of Frappe Bench. Like the command line utility it helps you install apps, manage multiple sites, update apps and much more. Install just by executing the following command in the respective bench directory.
$ bench setup manager
```
What all it does: bench setup manager
1. Create new site bench-manager.local
2. Gets the `bench_manager` app from https://github.com/frappe/bench_manager if it doesn't exist already
3. Installs the bench_manager app on the site bench-manager.local
## Docker Install - For Developers (beta) ---
# Docker Install
1. For developer setup, you can also use the official [Frappe Docker](https://github.com/frappe/frappe_docker/). 1. For developer setup, you can also use the official [Frappe Docker](https://github.com/frappe/frappe_docker/).
2. The app, mariadb and redis run on individual containers 2. The app, mariadb and redis run on individual containers.
3. This setup supports multi-tenancy and exposes the frappe-bench volume as a external storage. 3. This setup supports multi-tenancy and exposes the frappe-bench volume as a external storage.
4. For more details, [read the instructions on the Frappe Docker README](https://github.com/frappe/frappe_docker/) 4. For more details, [ead the instructions on the [Frappe Docker README](https://github.com/frappe/frappe_docker/)
---
Help # Guides
====
For bench help, you can type
bench --help
Updating
========
To manually update the bench, run `bench update` to update all the apps, run
patches, build JS and CSS files and restart supervisor (if configured to).
You can also run the parts of the bench selectively.
`bench update --pull` will only pull changes in the apps
`bench update --patch` will only run database migrations in the apps
`bench update --build` will only build JS and CSS files for the bench
`bench update --bench` will only update the bench utility (this project)
`bench update --requirements` will only update all dependencies (Python + Node) for the apps available in current bench
Guides
=======
- [Configuring HTTPS](https://frappe.io/docs/user/en/bench/guides/configuring-https.html) - [Configuring HTTPS](https://frappe.io/docs/user/en/bench/guides/configuring-https.html)
- [Using Let's Encrypt to setup HTTPS](https://frappe.io/docs/user/en/bench/guides/lets-encrypt-ssl-setup.html) - [Using Let's Encrypt to setup HTTPS](https://frappe.io/docs/user/en/bench/guides/lets-encrypt-ssl-setup.html)
- [Diagnosing the Scheduler](https://frappe.io/docs/user/en/bench/guides/diagnosing-the-scheduler.html) - [Diagnosing the Scheduler](https://frappe.io/docs/user/en/bench/guides/diagnosing-the-scheduler.html)
@ -233,10 +126,16 @@ Guides
- [Setup Multitenancy](https://frappe.io/docs/user/en/bench/guides/setup-multitenancy.html) - [Setup Multitenancy](https://frappe.io/docs/user/en/bench/guides/setup-multitenancy.html)
- [Stopping Production](https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development) - [Stopping Production](https://github.com/frappe/bench/wiki/Stopping-Production-and-starting-Development)
---
Resources # Resources
=======
- [Background Services](https://frappe.io/docs/user/en/bench/resources/background-services.html) - [Background Services](https://frappe.io/docs/user/en/bench/resources/background-services.html)
- [Bench Commands Cheat Sheet](https://frappe.io/docs/user/en/bench/resources/bench-commands-cheatsheet.html) - [Bench Commands Cheat Sheet](https://frappe.io/docs/user/en/bench/resources/bench-commands-cheatsheet.html)
- [Bench Procfile](https://frappe.io/docs/user/en/bench/resources/bench-procfile.html) - [Bench Procfile](https://frappe.io/docs/user/en/bench/resources/bench-procfile.html)
---
# License
bench is licensed under [GNU GPLv3](LICENSE)

69
docs/commands_and_usage.md Normal file
View File

@ -0,0 +1,69 @@
## Usage
* Updating
Currently, `bench update` can be run from any directory however the context of the command changes. If run from a bench directory, the vanilla command itself updates all apps, runs migrations and backs up all sites.
bench update
To manually update the bench, run `bench update` to update all the apps, run
patches, build JS and CSS files and restart supervisor (if configured to).
You can also run the parts of the bench selectively.
`bench update --pull` will only pull changes in the apps
`bench update --patch` will only run database migrations in the apps
`bench update --build` will only build JS and CSS files for the bench
`bench update --bench` will only update the bench utility (this project)
`bench update --requirements` will only update all dependencies (Python + Node) for the apps available in current bench
* Create a new bench
The init command will create a bench directory with frappe framework installed. It will be setup for periodic backups and auto updates once a day.
bench init frappe-bench && cd frappe-bench
* Add a site
Frappe apps are run by frappe sites and you will have to create at least one site. The new-site command allows you to do that.
bench new-site site1.local
* Add apps
The get-app command gets remote frappe apps from a remote git repository and installs them. Example: [erpnext](https://github.com/frappe/erpnext)
bench get-app erpnext https://github.com/frappe/erpnext
* Install apps
To install an app on your new site, use the bench `install-app` command.
bench --site site1.local install-app erpnext
* Start bench
To start using the bench, use the `bench start` command
bench start
To login to Frappe / ERPNext, open your browser and go to `[your-external-ip]:8000`, probably `localhost:8000`
The default username is "Administrator" and password is what you set when you created the new site.
* Setup Manager
## What it does
bench setup manager
1. Create new site bench-manager.local
2. Gets the `bench_manager` app from https://github.com/frappe/bench_manager if it doesn't exist already
3. Installs the bench_manager app on the site bench-manager.local

4
docs/contribution_guidelines.md
View File

@ -2,9 +2,9 @@
### Introduction (for first timers) ### Introduction (for first timers)
Thank you for your interesting in contributing to an open source project! Our world works on people taking initiative to contribute to the "commons" and contributing to open source means you are contributing to make things better for not only yourself, but everyone else too! So thank you for taking this initiative. Thank you for your interest in contributing to our project! Our world works on people taking initiative to contribute to the "commons" and contributing to open source means you are contributing to make things better for not only yourself, but everyone else too! So kudos to you for taking this initiative.
Great projects also work because of great quality. Open source or not, the user really cares that things should work as they are advertised, and consistently. New features should follow the same pattern and so that users don't have to learn things again and again. Great projects depend on good code quality and adhering to certain standards while making sure the goals of the project are met. New features should follow the same pattern and so that users don't have to learn things again and again.
Developers who maintain open source also expect that you follow certain guidelines. These guidelines ensure that developers are able quickly give feedback on your contribution and how to make it better. Most probably you might have to go back and change a few things, but it will be in th interest of making this process better for everyone. So do be prepared for some back and forth. Developers who maintain open source also expect that you follow certain guidelines. These guidelines ensure that developers are able quickly give feedback on your contribution and how to make it better. Most probably you might have to go back and change a few things, but it will be in th interest of making this process better for everyone. So do be prepared for some back and forth.

91
docs/easy_install.md Normal file
View File

@ -0,0 +1,91 @@
# Easy Install Script
- This script will install the pre-requisites, install bench and setup an ERPNext site `(site1.local under frappe-bench)`
- Passwords for Frappe Administrator and MariaDB (root) will be asked and saved under `~/passwoords.txt`
- MariaDB (root) password may be `password` on a fresh server
- You can then login as **Administrator** with the Administrator password
- The log file is saved under `/tmp/logs/install_bench.log` in case you run into any issues during the install.
- If you find any problems, post them on the forum: [https://discuss.erpnext.com](https://discuss.erpnext.com/tags/installation_problem) under the "Install / Update" category.
---
## What will this script do?
- Install all the pre-requisites
- Install the command line `bench` (under ~/.bench)
- Create a new bench (a folder that will contain your entire frappe/erpnext setup at ~/frappe-bench)
- Create a new ERPNext site on the bench (site1.local)
---
## Getting started with easy install...
Open your Terminal and enter:
#### 0. Setup user & Download the install script
If you are on a fresh server and logged in as root, at first create a dedicated user for frappe
& equip this user with sudo privileges
```
adduser [frappe-user]
usermod -aG sudo [frappe-user]
```
*(it is very common to use "frappe" as frappe-username, but this comes with the security flaw of ["frappe" ranking very high](https://www.reddit.com/r/dataisbeautiful/comments/b3sirt/i_deployed_over_a_dozen_cyber_honeypots_all_over/?st=JTJ0SC0Q&sh=76e05240) in as a username challenged in hacking attempts. So, for production sites it is highly recommended to use a custom username harder to guess)*
Switch to `[frappe-user]` (using `su [frappe-user]`) and start the setup
wget https://raw.githubusercontent.com/frappe/bench/master/playbooks/install.py
#### 1. Run the install script
sudo python3 install.py
*Note: `user` flag to create a user and install using that user (By default, the script will create a user with the username `frappe` if the --user flag is not used)*
For production or development, append teh `--production` or `--develop` flag to the command respectively.
sudo python3 install.py --production --user [frappe-user]
or
sudo python3 install.py --develop
sudo python3 install.py --develop --user [frappe-user]
sudo python3 install.py --production --user [frappe-user] --container
*Note: `container` flag to install inside a container (this will prevent the `/proc/sys/vm/swappiness: Read-only` file system error)*
python3 install.py --production --version 11 --user [frappe-user]
use --version flag to install specific version
python3 install.py --production --version 11 --python python2.7 --user [frappe-user]
use --python flag to specify virtual environments python version, by default script setup python3
---
## How do I start ERPNext
1. For development: Go to your bench folder (`frappe-bench` by default) and start the bench with `bench start`
2. For production: Your process will be setup and managed by `nginx` and `supervisor`. Checkout [Setup Production](https://frappe.io/docs/user/en/bench/guides/setup-production.html) for more information.
---
## An error occured mid installation?
TLDR; Save the logs!
1. The easy install script starts multiple processes to install prerequisites, system dependencies, requirements, sets up locales, configuration files, etc.
2. The script pipes all these process outputs and saves it under `/tmp/log/{easy-install-filename}.log` as prompted by the script in the beginning of the script or/and if something went wrong again.
3. Retain this log file and share it in case you need help with proceeding with the install. Since, the file's saved under `/tmp` it'll be cleared by the system after a reboot. Be careful to save it elsewhere if needed!
3. A lot of things can go wrong in setting up the environment due to prior settings, company protocols or even breaking changes in system packages and their dependencies.
4. Sharing your logfile in any issues opened related to this can help us find solutions to it faster and make the sript better!

38
docs/installation.md Normal file
View File

@ -0,0 +1,38 @@
### Requirements
You will need a computer/server. Options include:
- A Normal Computer/VPS/Baremetal Server: This is strongly recommended. Frappe/ERPNext installs properly and works well on these
- A Raspberry Pi, SAN Appliance, Network Router, Gaming Console, etc.: Although you may be able to install Frappe/ERPNext on specialized hardware, it is unlikely to work well and will be difficult for us to support. Strongly consider using a normal computer/VPS/baremetal server instead. **We do not support specialized hardware**.
- A Toaster, Car, Firearm, Thermostat, etc.: Yes, many modern devices now have embedded computing capability. We live in interesting times. However, you should not install Frappe/ERPNext on these devices. Instead, install it on a normal computer/VPS/baremetal server. **We do not support installing on noncomputing devices**.
To install the Frappe/ERPNext server software, you will need an operating system on your normal computer which is not Windows. Note that the command line interface does work on Windows, and you can use Frappe/ERPNext from any operating system with a web browser. However, the server software does not run on Windows. It does run on other operating systems, so choose one of these instead:
- Linux: Ubuntu, Debian, CentOS are the preferred distros and are tested. [Arch Linux](https://github.com/frappe/bench/wiki/Install-ERPNext-on-ArchLinux) can also be used
- Mac OS X
### Manual Install
To manually install frappe/erpnext, you can follow this [this wiki](https://github.com/frappe/frappe/wiki/The-Hitchhiker%27s-Guide-to-Installing-Frappe-on-Linux) for Linux and [this wiki](https://github.com/frappe/frappe/wiki/The-Hitchhiker's-Guide-to-Installing-Frappe-on-Mac-OS-X) for MacOS. It gives an excellent explanation about the stack. You can also follow the steps mentioned below:
#### 1. Install Prerequisites
<pre>
• Python 3.6+
• Node.js 12
• Redis 5 (caching and realtime updates)
• MariaDB 10.3 / Postgres 9.5 (to run database driven apps)
• yarn 1.12+ (js dependency manager)
• pip 15+ (py dependency manager)
• cron (scheduled jobs)
• wkhtmltopdf (version 0.12.5 with patched qt) (for pdf generation)
• Nginx (for production)
</pre>
#### 2. Install Bench
Install bench as a *non root* user,
git clone https://github.com/frappe/bench ~/.bench
pip3 install --user -e ~/.bench
Note: Please do not remove the bench directory the above commands will create

0
docs/releasing_frappe_erpext.md → docs/releasing_frappe_apps.md
View File