Skip to content

Commit

Permalink
document requirements and fix beautify make target (2600hz#6293)
Browse files Browse the repository at this point in the history 
* document dev time requirements

* fix fmt-view-all target to find json files from account correctly

* fix typos, add jsbeautifier, better wording, adding more info about kam and fs

* describe how to install erlang

* add shell syntax

* fix some leftovers and link to build time requirements
  • Loading branch information
@icehess
icehess authored Feb 8, 2020
1 parent b3a193d commit b3630d6
Show file tree
Hide file tree
Showing 4 changed files with 203 additions and 66 deletions.
10 changes: 5 additions & 5 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,10 @@ raw_json_check:
check_stacktrace:
@$(ROOT)/scripts/check-stacktrace.py $(shell grep -rl "get_stacktrace" scripts applications core --include "*.[e|h]rl" --exclude "kz_types.hrl")

## FIXME: `format-couchdb-view.py` command is a copy-paste from fmt.mk
## Adding this format couchdb view target to circleci steps for every app is painful
## also this formatting is better to be done before validate-js ci step to make sure
## the view is still in correct shape
apis:
@ERL_LIBS=deps:core:applications $(ROOT)/scripts/generate-schemas.escript
@$(ROOT)/scripts/format-json.py $(shell find applications core -wholename '*/schemas/*.json')
Expand All @@ -341,11 +345,7 @@ apis:
@$(ROOT)/scripts/format-json.py $(shell find applications core -wholename '*/api/*.json')
@ERL_LIBS=deps:core:applications $(ROOT)/scripts/generate-fs-headers-hrl.escript
@ERL_LIBS=deps:core:applications $(ROOT)/scripts/generate-kzd-builders.escript
## FIXME: copy-paste from fmt.mk fmt-views-all target
## adding that target to circleci steps for every app is painful
## also this formatting is better to be done before validate-js ci step to make sure
## the view is still in correct shape
@$(ROOT)/scripts/format-couchdb-views.py core/kazoo_apps/priv/couchdb/account
@$(ROOT)/scripts/format-couchdb-views.py $(shell find core/kazoo_apps/priv/couchdb/account -name '*.json')
@$(ROOT)/scripts/format-couchdb-views.py $(shell find applications core -wholename '*/couchdb/views/*.json')

schemas:
Expand Down
57 changes: 34 additions & 23 deletions core/kazoo_apps/priv/couchdb/account/attributes.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,20 +13,24 @@
"map": [
"function(doc) {",
" if (doc.pvt_type != 'resource' || !doc.enabled || doc.pvt_deleted) return;",
" for (var i in doc.rules) emit([doc.weight_cost, doc.rules[i]], {",
" 'id': doc._id,",
" 'gateways': doc.gateways,",
" 'caller_id_options': doc.caller_id_options,",
" 'flags': doc.flags || []",
" });",
" for (var i in doc.rules) {",
" emit([doc.weight_cost, doc.rules[i]], {",
" 'id': doc._id,",
" 'gateways': doc.gateways,",
" 'caller_id_options': doc.caller_id_options,",
" 'flags': doc.flags || []",
" });",
" }",
"}"
]
},
"endpoints_lookup": {
"map": [
"function(doc) {",
" if (typeof doc.caller_id === 'undefined') return;",
" for (var type in doc.caller_id) emit([doc.caller_id[type].number, type], doc.pvt_type);",
" for (var type in doc.caller_id) {",
" emit([doc.caller_id[type].number, type], doc.pvt_type);",
" }",
"}"
]
},
Expand All @@ -50,16 +54,18 @@
"map": [
"function(doc) {",
" if (doc.pvt_deleted) return;",
" var has_users = false,",
" o = (doc.hotdesk || {}).users || {};",
" for (var p in o)",
" var has_users = false;",
" var o = (doc.hotdesk || {}).users || {};",
" for (var p in o) {",
" if (o.hasOwnProperty(p)) {",
" has_users = true;",
" break;",
" } if (doc.hotdesk && doc.hotdesk.users && has_users) {",
" }",
" }",
" if (doc.hotdesk && doc.hotdesk.users && has_users) {",
" for (owner_id in doc.hotdesk.users) {",
" emit(owner_id, null);",
" };",
" }",
" }",
"}"
]
Expand All @@ -76,13 +82,15 @@
"map": [
"function(doc) {",
" if (doc.pvt_deleted) return;",
" var has_users = false,",
" o = (doc.hotdesk || {}).users || {};",
" for (var p in o)",
" var has_users = false;",
" var o = (doc.hotdesk || {}).users || {};",
" for (var p in o) {",
" if (o.hasOwnProperty(p)) {",
" has_users = true;",
" break;",
" } if (doc.hotdesk && doc.hotdesk.users && has_users) {",
" }",
" }",
" if (doc.hotdesk && doc.hotdesk.users && has_users) {",
" for (owner_id in doc.hotdesk.users) {",
" emit([owner_id, doc.pvt_type], doc._id);",
" };",
Expand All @@ -96,13 +104,15 @@
"map": [
"function(doc) {",
" if (doc.pvt_deleted) return;",
" var has_users = false,",
" o = (doc.hotdesk || {}).users || {};",
" for (var p in o)",
" var has_users = false;",
" var o = (doc.hotdesk || {}).users || {};",
" for (var p in o) {",
" if (o.hasOwnProperty(p)) {",
" has_users = true;",
" break;",
" } if (doc.hotdesk && doc.hotdesk.users && has_users) {",
" }",
" }",
" if (doc.hotdesk && doc.hotdesk.users && has_users) {",
" for (owner_id in doc.hotdesk.users) {",
" emit(doc._id, owner_id);",
" };",
Expand All @@ -117,10 +127,11 @@
"function(doc) {",
" if (doc.pvt_deleted) return;",
" var owners;",
" var users = [],",
" o = (doc.hotdesk || {}).users || {};",
" for (var p in o)",
" var users = [];",
" var o = (doc.hotdesk || {}).users || {};",
" for (var p in o) {",
" if (o.hasOwnProperty(p)) users.push(p);",
" }",
" if (doc.hotdesk && doc.hotdesk.users && users.length) {",
" owners = users;",
" } else if (doc.owner_id) {",
Expand Down
200 changes: 163 additions & 37 deletions doc/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,75 +6,197 @@ If your development is on macOS, here are [extra steps](https://github.com/2600h

## Dependencies

### Erlang

### Packages Required
Erlang/OTP is required for both run time and build time. Usually the official Erlang package provided by distributions is not up-to-date, please follow this section to install it from source code or using other options.

#### Debian 9
```shell
sudo apt-get install build-essential libxslt-dev \
zip unzip expat zlib1g-dev libssl-dev curl \
libncurses5-dev git-core libexpat1-dev \
htmldoc
```
* Kazoo version 4.3 requires Erlang version 19 specifically 19.3.x
* Kazoo version 5.x is currently targets Erlang version 21 (specifically 21.3)
* Kazoo master branch targets Erlang 21+ (specifically 21.3 but consult [`make/erlang_version`](https://github.com/2600hz/kazoo/blob/master/make/erlang_version) to be sure).

#### Installing Erlang/OTP from source code

We recommend to use a tool like [kerl](https://github.com/kerl/kerl) to manage Erlang/OTP installations. If you want to play around with multiple versions of Erlang while hacking on Kazoo, this is probably the best way. For compiling Erlang you need some dependencies, see [Build time requirements](#build-time-requirements)

#### CentOS 7
```shell
sudo yum install openssl-devel automake autoconf ncurses-devel gcc python36-pip fop
curl -O https://raw.githubusercontent.com/kerl/kerl/master/kerl
chmod +x kerl
mv kerl /usr/bin
kerl list releases
kerl build 21.3 21.3 # this takes a while
kerl install 21.3 /usr/local/otp-21.3
. /usr/local/otp-19.3/activate
```

Note: `htmldoc` is required only if [you want to be able to download PDFs](./announcements.md#company-directory-pdf).
You will probably want to add the `activate` command to your `.bashrc` or similar to make sure the proper OTP version is running.

1. Docs-related
#### Installing from Erlang Solutions repository

When running `make docs`, some Python libraries are useful:
Most OS package managers provide pre-built binary packages. You can also download the latest stable releases [from Erlang Solutions](https://www.erlang-solutions.com/resources/download.html). Erlang Solutions provides [pre-built binary packages](https://www.erlang-solutions.com/resources/download.html) for OS X, Windows, Ubuntu, Debian, Fedora, CentOS, Raspbian and other operating systems.

```shell
sudo apt-get install python3 python3-yaml
sudo pip install mkdocs mkdocs-bootstrap mkdocs-bootswatch pymdown-extensions
```
* For Homebrew on maxOS: `brew install erlang`
* For Ubuntu and Debian: `apt-get install erlang`
* For CentOS/RHEL/Fedora: `yum install erlang`
* For FreeBSD: `pkg install erlang`

You can also run a local version of the docs with `make docs-serve` which will start a local server so you can view how the docs are rendered.

If you have a custom theme, you can copy it to `doc/mkdocs/theme` and build the docs again. When you serve the docs the theme should have been applied to the site.
### Packages Required

#### Build time requirements

### Erlang
* General Linux development build packages (GNU Make v4+ is recommended):
* `autoconf`, `automake`, `make`, `gcc`, `readline`
* `openssl`, `libcurl`, `ncurses`, `zlib`, `bzip2`, `expat`
* `git`
* Build time script requirements
* `cpio` required for building docs
* Python 3.5+
* Python 3 packages for building docs:
* `yaml`, `markdown`, `pyembed`
* `mkdocs-bootstrap`, `mkdocs-bootswatch`, `pymdown-extensions`
* `couchdb` (`validate-js` required `couchjs` command from CouchDB 2 to validate CouchDB view JavaScript codes)
* Python 3 packages `jsonschema`, `jsbeautifier` for validating JSON schemas and formatting CouchDB views
* `silversearcher-ag` required by `scripts/edocify.escript`

#### Run time requirements

Main functionality requirements:

* CouchDB 2
* Please consult [CouchDB installation doc](https://docs.couchdb.org/en/stable/install/index.html)
* **Note:** Old abandoned BigCouch can be used too but this is not recommended for new clusters
* RabbitMQ
* Please consult [RabbitMQ installation doc](https://www.rabbitmq.com/download.html)
* Recommended official 2600Hz [RabbitMQ configurations](https://github.com/2600hz/kazoo-configs-rabbitmq)
* **Note:** Kazoo 5 (master) requires `rabbitmq_consistent_hash_exchange` plug-in to be enabled for Kazoo Fax application

Voice/Video and SIP functionality requirements:

* FreeSWITCH version 1.10+
* It is required `mod_kazoo` plug-in to be enabled
* Official 2600Hz [FreeSWITCH configurations](https://github.com/2600hz/kazoo-configs-freeswitch) is required
* It is recommended to install FreeSWITCH from [2600Hz CentOS repository](https://docs.2600hz.com/sysadmin/doc/install/install_via_centos7) to ease the installation.
* Kamailio version 5.2+
* It is required `kazoo` module to be enabled
* Official 2600Hz [Kamailio configurations](https://github.com/2600hz/kazoo-configs-kamailio) is required
* It is recommended to install Kamailio from [2600Hz CentOS repository](https://docs.2600hz.com/sysadmin/doc/install/install_via_centos7) to ease the installation.
* If you're installing the official Kamailio packages instead, you have to change the database in 2600Hz Kamailio configurations to use `sqlite` or you're choice of database.

Kazoo 5.x targets Erlang 21+ (specifically 21.3 but consult [`make/erlang_version`](https://github.com/2600hz/kazoo/blob/master/make/erlang_version) to be sure). There are a couple ways to install Erlang:

1. From Source
Other packages:

I prefer to use a tool like [kerl](https://github.com/kerl/kerl) to manage my installations. If you want to play around with multiple versions of Erlang while hacking on Kazoo, this is probably the best way.
* `zip`, `unzip`
* `htmldoc` required if [you want to be able to download PDFs](./announcements.md#company-directory-pdf)
* `sox` for normalizing audio files (Debian needs `libsox-fmt-all` to support MP3 audio format)
* `ghostscript`, `imagemagick` `libtiff-tools`, `libreoffice-writer` with Java Run time environment for Fax functionality and fax media file conversions

Useful commands:

* `sudo`, `less`, `whois`, `strace`, `tcpdump`, `net-tools`
* `ntpdate`, `bind-utils`, `which`, `file`, `psmisc`, `iproute`, `lsof`


### Installing dependencies on Debian 9+

```shell
curl -O https://raw.githubusercontent.com/kerl/kerl/master/kerl
chmod +x kerl
mv kerl /usr/bin
kerl list releases
kerl build 21.3 21.3 # this takes a while
kerl install 21.3 /usr/local/otp-21.3
. /usr/local/otp-19.3/activate
## Adding official CouchDB 2 repo
sudo apt-get install apt-transport-https
echo "deb https://apache.bintray.com/couchdb-deb stretch main" | sudo tee -a /etc/apt/sources.list
curl -L https://couchdb.apache.org/repo/bintray-pubkey.asc | sudo apt-key add -

## Kazoo buildtime dependencies
sudo apt-get install \
build-essential libxslt-dev \
zip unzip expat zlib1g-dev libssl-dev curl \
libncurses5-dev git-core libexpat1-dev \
python3-yaml python3-markdown python3-jsonschema python3-pip \
python3-jsbeautifier \
cpio mkdocs \
couchdb \
silversearcher-ag jq

## doc build target
sudo pip3 install pyembed mkdocs-bootstrap mkdocs-bootswatch pymdown-extensions

## Kazoo runtime dependencies
sudo apt-get install \
htmldoc sox libsox-fmt-all ghostscript \
imagemagick libtiff-tools openjdk-8-jre libreoffice-writer

## Linking couchjs so validate-js script can find it
sudo ln -s /opt/couchdb/bin/couchjs /usr/bin/couchjs

## don't forget to uncomment "en_US.UTF-8 UTF-8" line (and your choice of language)
## from /etc/locale.gen file and run the command below:
sudo locale-gen
```

You will probably want to add the `activate` command to your `.bashrc` or similar to make sure the proper OTP version is running.

2. Erlang Solutions

Install from the [Erlang Solutions](https://www.erlang-solutions.com/resources/download.html) packages. These tend to be kept up-to-date better than the default distro's packages.
### Installing dependencies on CentOS 7

```shell
## Adding useful repos
sudo cat <<'EOF' > /etc/yum.repos.d/bintray-apache-couchdb-rpm.repo
[bintray--apache-couchdb-rpm]
name=bintray--apache-couchdb-rpm
baseurl=http://apache.bintray.com/couchdb-rpm/el7/$basearch/
gpgcheck=0
repo_gpgcheck=0
enabled=1
EOF


sudo yum install epel-release
sudo yum update

## kazoo master (5.0+) needs git2
sudo yum remove -y git*
sudo yum install https://centos7.iuscommunity.org/ius-release.rpm

## Kazoo buildtime dependencies
sudo yum install \
autoconf automake bzip2-devel elfutils expat-devel gcc-c++ gcc \
git2u-all glibc-devel libcurl libcurl-devel libstdc++-devel \
libxslt make ncurses-devel openssl openssl-devel patch \
patchutils readline readline-devel unzip wget zip zlib-devel \
python36-pip the_silver_searcher jq cpio

## installing required (and optional docs building) python packages
sudo pip3 install pyyaml markdown jsonschema jsbeautifier

## doc build target
sudo pip3 install pyembed mkdocs-bootstrap mkdocs-bootswatch pymdown-extensions

## Kazoo runtime dependencies
sudo yum install \
htmldoc sox ghostscript \
ImageMagick libtiff-tools libreoffice-writer

## make sure UTF-8 locale is set correctly
localedef -v -c -i en_US -f UTF-8 en_US.UTF-8
```

## Building Kazoo

### Short version

```shell
cd /opt
git clone https://github.com/2600Hz/kazoo.git
cd kazoo
make
```

### Building and serving local version of documentation site

You following command to build documentation site:

```shell
make docs
```

You can also run a local version of the docs with `make docs-serve` which will start a local server so you can view how the docs are rendered.
If you have a custom theme, you can copy it to `doc/mkdocs/theme` and build the docs again. When you serve the docs the theme should have been applied to the site.


### Longer version

Expand All @@ -96,10 +218,14 @@ make
When developing, one can `cd` into any app directory (within `applications/` or `core/`) and run:

- `make` (`make all` or `make clean`)
- `make apis` to build document accessors, Crossbar API OpenAPI, JSON schemas and etc...
- `make xref` to look for calls to undefined functions (uses [Xref](http://www.erlang.org/doc/apps/tools/xref_chapter.html))
- `make dialyze` to statically type-check the app (uses [Dialyzer](http://www.erlang.org/doc/man/dialyzer.html))
- `make fmt` to format Erlang source codes to the standard
- `make fmt-views-all` to format JavaScript codes inside CouchDB view files
- `make test` runs the app / sub-apps test suite, if any.
- **Note:** make sure to `make clean all` after running your tests, as test BEAMs are generated in `ebin/`!
- Consult `Makefile` for more Makefile targets

4. Running the tests

Expand All @@ -120,7 +246,7 @@ make

6. Generate an Erlang development release

`make build-dev-release` will generate a development release.
`make build-dev-release` will generate a development release with symlinking beams files and reload them when they re-compiled to ease development

7. Start an Erlang development release

Expand Down
Loading

0 comments on commit b3630d6

Please sign in to comment.