github.com/rpdict/ponzu@v0.10.1-0.20190226054626-477f29d6bf5e/README.md (about) 1  2 3 # Ponzu 4 [](https://github.com/rpdict/ponzu/releases/latest) 5 [](https://godoc.org/github.com/rpdict/ponzu) 6 [](https://goreportcard.com/report/github.com/rpdict/ponzu) 7 [](https://circleci.com/gh/ponzu-cms/ponzu/tree/master) 8 9 > Watch the [**video introduction**](https://www.youtube.com/watch?v=T_1ncPoLgrg) 10 11 Ponzu is a powerful and efficient open-source HTTP server framework and CMS. It 12 provides automatic, free, and secure HTTP/2 over TLS (certificates obtained via 13 [Let's Encrypt](https://letsencrypt.org)), a useful CMS and scaffolding to 14 generate content editors, and a fast HTTP API on which to build modern applications. 15 16 Ponzu is released under the BSD-3-Clause license (see LICENSE). 17 (c) [Boss Sauce Creative, LLC](https://bosssauce.it) 18 19 ## Why? 20 With the rise in popularity of web/mobile apps connected to JSON HTTP APIs, better 21 tools to support the development of content servers and management systems are necessary. 22 Ponzu fills the void where you want to reach for Wordpress to get a great CMS, or Rails for 23 rapid development, but need a fast JSON response in a high-concurrency environment. 24 25 **Because you want to turn this:** 26 ```bash 27 $ ponzu gen content song title:"string" artist:"string" rating:"int" opinion:"string":richtext spotify_url:"string" 28 ``` 29 30 **Into this:** 31 32  33 34 35 **What's inside** 36 - Automatic & Free SSL/TLS<sup id="a1">[1](#f1)</sup> 37 - HTTP/2 and Server Push 38 - Rapid development with CLI-controlled code generators 39 - User-friendly, extensible CMS and administration dashboard 40 - Simple deployment - single binary + assets, embedded DB ([BoltDB](https://github.com/boltdb/bolt)) 41 - Fast, helpful framework while maintaining control 42 43 <sup id="f1">1</sup> *TLS*: 44 - Development: self-signed certificates auto-generated 45 - Production: auto-renewing certificates fetched from [Let's Encrypt](https://letsencrypt.org) 46 47 [↩](#a1) 48 49 ## Documentation 50 For more detailed documentation, check out the [docs](https://docs.ponzu-cms.org) 51 52 ## Installation 53 54 ``` 55 $ go get -u github.com/rpdict/ponzu/... 56 ``` 57 58 ## Requirements 59 Go 1.8+ 60 61 Since HTTP/2 Server Push is used, Go 1.8+ is required. However, it is not 62 required of clients connecting to a Ponzu server to make HTTP/2 requests. 63 64 ## Usage 65 66 ```bash 67 $ ponzu command [flags] <params> 68 ``` 69 70 ## Commands 71 72 ### new 73 74 Creates a project directory of the name supplied as a parameter immediately 75 following the 'new' option in the $GOPATH/src directory. Note: 'new' depends on 76 the program 'git' and possibly a network connection. If there is no local 77 repository to clone from at the local machine's $GOPATH, 'new' will attempt to 78 clone the 'github.com/rpdict/ponzu' package from over the network. 79 80 Example: 81 ```bash 82 $ ponzu new github.com/nilslice/proj 83 > New ponzu project created at $GOPATH/src/github.com/nilslice/proj 84 ``` 85 86 Errors will be reported, but successful commands return nothing. 87 88 --- 89 90 ### generate, gen, g 91 92 Generate boilerplate code for various Ponzu components, such as `content`. 93 94 Example: 95 ```bash 96 generator struct fields and built-in types... 97 | | 98 v v 99 $ ponzu gen content review title:"string" body:"string":richtext rating:"int" 100 ^ ^ 101 | | 102 struct type (optional) input view specifier 103 ``` 104 105 The command above will generate the file `content/review.go` with boilerplate 106 methods, as well as struct definition, and corresponding field tags like: 107 108 ```go 109 type Review struct { 110 Title string `json:"title"` 111 Body string `json:"body"` 112 Rating int `json:"rating"` 113 } 114 ``` 115 116 The generate command will intelligently parse more sophisticated field names 117 such as 'field_name' and convert it to 'FieldName' and vice versa, only where 118 appropriate as per common Go idioms. Errors will be reported, but successful 119 generate commands return nothing. 120 121 **Input View Specifiers** _(optional)_ 122 123 The CLI can optionally parse a third parameter on the fields provided to generate 124 the type of HTML view an editor field is presented within. If no third parameter 125 is added, a plain text HTML input will be generated. In the example above, the 126 argument shown as `body:string:richtext` would show the Richtext input instead 127 of a plain text HTML input (as shown in the screenshot). The following input 128 view specifiers are implemented: 129 130 | CLI parameter | Generates | 131 |---------------|-----------| 132 | checkbox | `editor.Checkbox()` | 133 | custom | generates a pre-styled empty div to fill with HTML | 134 | file | `editor.File()` | 135 | hidden | `editor.Input()` + uses type=hidden | 136 | input, text | `editor.Input()` | 137 | richtext | `editor.Richtext()` | 138 | select | `editor.Select()` | 139 | textarea | `editor.Textarea()` | 140 | tags | `editor.Tags()` | 141 142 --- 143 144 ### build 145 146 From within your Ponzu project directory, running build will copy and move 147 the necessary files from your workspace into the vendored directory, and 148 will build/compile the project to then be run. 149 150 Optional flags: 151 - `--gocmd` sets the binary used when executing `go build` within `ponzu` build step 152 153 Example: 154 ```bash 155 $ ponzu build 156 (or) 157 $ ponzu build --gocmd=go1.8rc1 # useful for testing 158 ``` 159 160 Errors will be reported, but successful build commands return nothing. 161 162 --- 163 164 ### run 165 166 Starts the HTTP server for the JSON API, Admin System, or both. 167 The segments, separated by a comma, describe which services to start, either 168 'admin' (Admin System / CMS backend) or 'api' (JSON API), and, optionally, 169 if the server should utilize TLS encryption - served over HTTPS, which is 170 automatically managed using Let's Encrypt (https://letsencrypt.org) 171 172 Optional flags: 173 - `--port` sets the port on which the server listens for HTTP requests [defaults to 8080] 174 - `--https-port` sets the port on which the server listens for HTTPS requests [defaults to 443] 175 - `--https` enables auto HTTPS management via Let's Encrypt (port is always 443) 176 - `--dev-https` generates self-signed SSL certificates for development-only (port is 10443) 177 178 Example: 179 ```bash 180 $ ponzu run 181 (or) 182 $ ponzu run --port=8080 --https admin,api 183 (or) 184 $ ponzu run admin 185 (or) 186 $ ponzu run --port=8888 api 187 (or) 188 $ ponzu run --dev-https 189 ``` 190 Defaults to `$ ponzu run --port=8080 admin,api` (running Admin & API on port 8080, without TLS) 191 192 *Note:* 193 Admin and API cannot run on separate processes unless you use a copy of the 194 database, since the first process to open it receives a lock. If you intend 195 to run the Admin and API on separate processes, you must call them with the 196 'ponzu' command independently. 197 198 --- 199 200 ### upgrade 201 202 Will backup your own custom project code (like content, add-ons, uploads, etc) so 203 we can safely re-clone Ponzu from the latest version you have or from the network 204 if necessary. Before running `$ ponzu upgrade`, you should update the `ponzu` 205 package by running `$ go get -u github.com/rpdict/ponzu/...` 206 207 Example: 208 ```bash 209 $ ponzu upgrade 210 ``` 211 212 --- 213 214 ### add, a 215 216 Downloads an add-on to GOPATH/src and copys it to the Ponzu project's ./addons directory. 217 Must be called from within a Ponzu project directory. 218 219 Example: 220 ```bash 221 $ ponzu add github.com/bosssauce/fbscheduler 222 ``` 223 224 Errors will be reported, but successful add commands return nothing. 225 226 --- 227 228 ### version, v 229 230 Prints the version of Ponzu your project is using. Must be called from within a 231 Ponzu project directory. By passing the `--cli` flag, the `version` command will 232 print the version of the Ponzu CLI you have installed. 233 234 Example: 235 ```bash 236 $ ponzu version 237 > Ponzu v0.8.2 238 (or) 239 $ ponzu version --cli 240 > Ponzu v0.9.2 241 ``` 242 243 --- 244 245 ## Contributing 246 247 1. Checkout branch ponzu-dev 248 2. Make code changes 249 3. Test changes to ponzu-dev branch 250 - make a commit to ponzu-dev 251 - to manually test, you will need to use a new copy (ponzu new path/to/code), but pass the --dev flag so that ponzu generates a new copy from the ponzu-dev branch, not master by default (i.e. `$ponzu new --dev /path/to/code`) 252 - build and run with $ ponzu build and $ ponzu run 253 4. To add back to master: 254 - first push to origin ponzu-dev 255 - create a pull request 256 - will then be merged into master 257 258 _A typical contribution workflow might look like:_ 259 ```bash 260 # clone the repository and checkout ponzu-dev 261 $ git clone https://github.com/rpdict/ponzu path/to/local/ponzu # (or your fork) 262 $ git checkout ponzu-dev 263 264 # install ponzu with go get or from your own local path 265 $ go get github.com/rpdict/ponzu/... 266 # or 267 $ cd /path/to/local/ponzu 268 $ go install ./... 269 270 # edit files, add features, etc 271 $ git add -A 272 $ git commit -m 'edited files, added features, etc' 273 274 # now you need to test the feature.. make a new ponzu project, but pass --dev flag 275 $ ponzu new --dev /path/to/new/project # will create $GOPATH/src/path/to/new/project 276 277 # build & run ponzu from the new project directory 278 $ cd /path/to/new/project 279 $ ponzu build && ponzu run 280 281 # push to your origin:ponzu-dev branch and create a PR at ponzu-cms/ponzu 282 $ git push origin ponzu-dev 283 # ... go to https://github.com/rpdict/ponzu and create a PR 284 ``` 285 286 **Note:** if you intend to work on your own fork and contribute from it, you will 287 need to also pass `--fork=path/to/your/fork` (using OS-standard filepath structure), 288 where `path/to/your/fork` _must_ be within `$GOPATH/src`, and you are working from a branch 289 called `ponzu-dev`. 290 291 For example: 292 ```bash 293 # ($GOPATH/src is implied in the fork path, do not add it yourself) 294 $ ponzu new --dev --fork=github.com/nilslice/ponzu /path/to/new/project 295 ``` 296 297 298 ## Credits 299 - [golang.org/x/text/unicode/norm](https://golang.org/x/text/unicode/norm) 300 - [golang.org/x/text/transform](https://golang.org/x/text/transform) 301 - [golang.org/x/crypto/bcrypt](https://golang.org/x/crypto/bcrypt) 302 - [golang.org/x/net/http2](https://golang.org/x/net/http2) 303 - [github.com/blevesearch/bleve](https://github.com/blevesearch/bleve) 304 - [github.com/nilslice/jwt](https://github.com/nilslice/jwt) 305 - [github.com/nilslice/email](https://github.com/nilslice/email) 306 - [github.com/gorilla/schema](https://github.com/gorilla/schema) 307 - [github.com/gofrs/uuid](https://github.com/gofrs/uuid) 308 - [github.com/tidwall/gjson](https://github.com/tidwall/gjson) 309 - [github.com/tidwall/sjson](https://github.com/tidwall/sjson) 310 - [github.com/boltdb/bolt](https://github.com/boltdb/bolt) 311 - [github.com/spf13/cobra](github.com/spf13/cobra) 312 - [Materialnote Editor](https://github.com/Cerealkillerway/materialNote) 313 - [Materialize.css](https://github.com/Dogfalo/materialize) 314 - [jQuery](https://github.com/jquery/jquery) 315 - [Chart.js](https://github.com/chartjs/Chart.js) 316 317 318 ### Logo 319 The Go gopher was designed by Renee French. (http://reneefrench.blogspot.com) 320 The design is licensed under the Creative Commons 3.0 Attributions license. 321 Read this article for more details: http://blog.golang.org/gopher 322 323 The Go gopher vector illustration by Hugo Arganda [@argandas](https://twitter.com/argandas) (http://about.me/argandas) 324 325 "Gotoro", the sushi chef, is a modification of Hugo Arganda's illustration by Steve Manuel (https://github.com/nilslice).