README.md 4.65 KB
Newer Older
1
# Hippo Essentials
2
Hippo Essentials is for developers who want to setup a new [Hippo CMS](http://www.onehippo.org) project. It enables
Tobias Jeger's avatar
Tobias Jeger committed
3 4
them to kickstart their project in a matter of minutes, to benefit from our best practices and to easily add Enterprise
or community plugins from the Hippo Marketplace.
Marijan Milicevic's avatar
Marijan Milicevic committed
5 6

```
Tobias Jeger's avatar
Tobias Jeger committed
7 8
Please use the Hippo Essentials feedback form to inform us if you encounter any bugs/glitches or if you have any
suggestions for improvements.
Marijan Milicevic's avatar
Marijan Milicevic committed
9 10
```

11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
# Prerequisites

* Java 8
* Maven 3.x
* Git (http://git-scm.com)
* NodeJS (http://nodejs.org/) 0.10+
* Node Package Manager (http://npmjs.org)
* Grunt (http://gruntjs.org)
* Bower (http://bower.io)

Grunt and Bower can be installed with Node Package Manager:

```shell
sudo npm install -g grunt-cli bower
```

If Bower fails to download zipped dependencies, make sure it uses decompress-zip >= 0.0.4.
(e.g. check the file /usr/lib/node_modules/bower/node_modules/decompress-zip/package.json,
and reinstall Bower if decompress-zip is too old).

## Windows specific preparation instructions

You can automate the installation of NodeJS and NPM using [Chocolatey package manager]
(https://chocolatey.org).

The package for Node.js can be installed using (this will also install NPM):

    C:\> choco install nodejs.install

__Note:__ Due to a [bug] (http://jira.codehaus.org/browse/MEXEC-137) in the exec-maven-plugin the Maven build of the
API module will fail as the exec-maven-plugin is unable to find the __grunt__ and __bower__ commands. To fix this, do
the following:

* open folder `C:\Users\USER\AppData\Roaming\npm`
* copy __grunt.cmd__ to __grunt.bat__
* copy __bower.cmd__ to __bower.bat__

More information can be found [here] (http://stackoverflow.com/questions/22393785/exec-maven-plugin-says-cannot-run-specified-program-even-though-it-is-on-the-pa/22395703#22395703).

Installation of Git is also possible using Chocolatey:

    C:\> choco install git.install


55
# Getting Started
Jeroen Reijn's avatar
Jeroen Reijn committed
56

57
## SVN checkout
Dirkjan van Diepen's avatar
Dirkjan van Diepen committed
58

59 60 61
To get started with the Hippo Essentials, checkout the code. You have two options to check out
the project. The example commands below use the potentially unstable trunk snapshot. Consider
using a tag instead.
Dirkjan van Diepen's avatar
Dirkjan van Diepen committed
62

63 64
### Read-only
```shell
65
svn co http://svn.onehippo.org/repos/hippo/hippo-cms7/essentials/trunk essentials
66
```
Dirkjan van Diepen's avatar
Dirkjan van Diepen committed
67

68
### Read-write (you'll need Hippo SVN account for this)
69
```shell
70
svn co https://svn.onehippo.org/repos/hippo/hippo-cms7/essentials/trunk essentials
Dirkjan van Diepen's avatar
Dirkjan van Diepen committed
71
```
72

73
### Build the essentials components:
74 75 76
```shell
cd essentials
mvn clean install
Marijan Milicevic's avatar
Marijan Milicevic committed
77
```
78

79
### Validate license headers:
80 81
```shell
mvn clean && mvn validate -Ppedantic
82 83
```

84
### Create and install archetype locally:
85
```shell
86
svn co http://svn.onehippo.org/repos/hippo/hippo-cms7/archetype/trunk/ archetype
87
cd archetype
88
mvn clean install
Marijan Milicevic's avatar
Marijan Milicevic committed
89
```
90

91
### Generate a new Hippo project from the archetype (use appropriate archetype version):
92
```shell
93
mvn archetype:generate -D "archetypeGroupId=org.onehippo.cms7" -D "archetypeArtifactId=hippo-project-archetype" -D "archetypeVersion=[archetype version]"
94 95
```

96 97 98 99
##Running locally


This project uses the Maven Cargo plugin to run the CMS, Website and Essentials dashboard locally in Tomcat.
Jeroen Reijn's avatar
Jeroen Reijn committed
100 101
From the project root folder, execute:

102
```shell
103 104
mvn clean verify
mvn -P cargo.run -Drepo.path=storage
105 106 107 108 109 110
```

The following URLs are available from this project:

 * CMS at http://localhost:8080/cms
 * Website at http://localhost:8080/site 
Kenan Salic's avatar
Kenan Salic committed
111
 * Essentials dashboard at http://localhost:8080/essentials
112

113
Logs are located in `target/tomcat8x/logs`
Jeroen Reijn's avatar
Jeroen Reijn committed
114

115
##Using JRebel
Jeroen Reijn's avatar
Jeroen Reijn committed
116

117
Set the environment variable `REBEL_HOME` to the directory containing jrebel.jar.
Jeroen Reijn's avatar
Jeroen Reijn committed
118 119 120

Build with:

121 122
```shell
mvn clean install -Djrebel
123
```
Jeroen Reijn's avatar
Jeroen Reijn committed
124 125 126

Start with:

127 128
```shell
mvn -P cargo.run -Djrebel
129
```
Jeroen Reijn's avatar
Jeroen Reijn committed
130

131
##Best Practice for development
Jeroen Reijn's avatar
Jeroen Reijn committed
132

133
Use the option `-Drepo.path=/some/path/to/repository` during start up. This will avoid
Jeroen Reijn's avatar
Jeroen Reijn committed
134 135 136 137
your repository to be cleared when you do a mvn clean.

For example start your project with:

138 139
```shell
mvn -P cargo.run -Drepo.path=/home/usr/tmp/repo
140
```
Jeroen Reijn's avatar
Jeroen Reijn committed
141 142
or with jrebel:

143 144
```shell
mvn -P cargo.run -Drepo.path=/home/usr/tmp/repo -Djrebel
145 146
```
##Hot deploy
Jeroen Reijn's avatar
Jeroen Reijn committed
147 148 149

To hot deploy, redeploy or undeploy the CMS or site:

150 151 152
```shell
cd cms (or site)
mvn cargo:redeploy (or cargo:undeploy, or cargo:deploy)
153 154 155
```

##Automatic Export
Jeroen Reijn's avatar
Jeroen Reijn committed
156

157 158 159
Essentials depends on the automatic export feature being enabled, which is the archetype-generated Hippo
project's default setting. You can change the setting temporarily in the upper right corner in the CMS,
or permanently in your project's file
160
`./bootstrap/configuration/src/main/resources/configuration/modules/autoexport-module.xml`
Jeroen Reijn's avatar
Jeroen Reijn committed
161

162
##Copyright and license
Jeroen Reijn's avatar
Jeroen Reijn committed
163

164 165
Copyright 2013-2015 Hippo B.V.
Distributed under the [Apache 2.0 license](http://svn.onehippo.org/repos/hippo/hippo-cms7/essentials/trunk/LICENSE).
Marijan Milicevic's avatar
Marijan Milicevic committed
166