README

Ponzu

Current Release GoDoc Go Report Card CircleCI Build Status

Watch the video introduction

Ponzu is a powerful and efficient open-source HTTP server framework and CMS. It provides automatic, free, and secure HTTP/2 over TLS (certificates obtained via Let's Encrypt), a useful CMS and scaffolding to generate content editors, and a fast HTTP API on which to build modern applications.

Ponzu is released under the BSD-3-Clause license (see LICENSE). (c) Boss Sauce Creative, LLC

Why?

With the rise in popularity of web/mobile apps connected to JSON HTTP APIs, better tools to support the development of content servers and management systems are necessary. Ponzu fills the void where you want to reach for Wordpress to get a great CMS, or Rails for rapid development, but need a fast JSON response in a high-concurrency environment.

Because you want to turn this:

$ ponzu gen content song title:"string" artist:"string" rating:"int" opinion:"string":richtext spotify_url:"string"

Into this:

Generated content/song.go

What's inside

  • Automatic & Free SSL/TLS1
  • HTTP/2 and Server Push
  • Rapid development with CLI-controlled code generators
  • User-friendly, extensible CMS and administration dashboard
  • Simple deployment - single binary + assets, embedded DB (BoltDB)
  • Fast, helpful framework while maintaining control

1 TLS:

  • Development: self-signed certificates auto-generated
  • Production: auto-renewing certificates fetched from Let's Encrypt

Documentation

For more detailed documentation, check out the docs

Installation

$ go get -u github.com/ponzu-cms/ponzu/...

Requirements

Go 1.8+

Since HTTP/2 Server Push is used, Go 1.8+ is required. However, it is not required of clients connecting to a Ponzu server to make HTTP/2 requests.

Usage

$ ponzu command [flags] <params>

Commands

new

Creates a project directory of the name supplied as a parameter immediately following the 'new' option in the $GOPATH/src directory. Note: 'new' depends on the program 'git' and possibly a network connection. If there is no local repository to clone from at the local machine's $GOPATH, 'new' will attempt to clone the 'github.com/ponzu-cms/ponzu' package from over the network.

Example:

$ ponzu new github.com/nilslice/proj
> New ponzu project created at $GOPATH/src/github.com/nilslice/proj

Errors will be reported, but successful commands return nothing.


generate, gen, g

Generate boilerplate code for various Ponzu components, such as content.

Example:

            generator      struct fields and built-in types...
             |              |
             v              v    
$ ponzu gen content review title:"string" body:"string":richtext rating:"int"
                     ^                                   ^
                     |                                   |
                    struct type                         (optional) input view specifier

The command above will generate the file content/review.go with boilerplate methods, as well as struct definition, and corresponding field tags like:

type Review struct {
	Title  string   `json:"title"`
	Body   string   `json:"body"`
	Rating int      `json:"rating"`
}

The generate command will intelligently parse more sophisticated field names such as 'field_name' and convert it to 'FieldName' and vice versa, only where appropriate as per common Go idioms. Errors will be reported, but successful generate commands return nothing.

Input View Specifiers (optional)

The CLI can optionally parse a third parameter on the fields provided to generate the type of HTML view an editor field is presented within. If no third parameter is added, a plain text HTML input will be generated. In the example above, the argument shown as body:string:richtext would show the Richtext input instead of a plain text HTML input (as shown in the screenshot). The following input view specifiers are implemented:

CLI parameter Generates
checkbox editor.Checkbox()
custom generates a pre-styled empty div to fill with HTML
file editor.File()
hidden editor.Input() + uses type=hidden
input, text editor.Input()
richtext editor.Richtext()
select editor.Select()
textarea editor.Textarea()
tags editor.Tags()

build

From within your Ponzu project directory, running build will copy and move the necessary files from your workspace into the vendored directory, and will build/compile the project to then be run.

Optional flags:

  • --gocmd sets the binary used when executing go build within ponzu build step

Example:

$ ponzu build
(or)
$ ponzu build --gocmd=go1.8rc1 # useful for testing

Errors will be reported, but successful build commands return nothing.


run

Starts the HTTP server for the JSON API, Admin System, or both. The segments, separated by a comma, describe which services to start, either 'admin' (Admin System / CMS backend) or 'api' (JSON API), and, optionally, if the server should utilize TLS encryption - served over HTTPS, which is automatically managed using Let's Encrypt (https://letsencrypt.org)

Optional flags:

  • --port sets the port on which the server listens for HTTP requests [defaults to 8080]
  • --https-port sets the port on which the server listens for HTTPS requests [defaults to 443]
  • --https enables auto HTTPS management via Let's Encrypt (port is always 443)
  • --dev-https generates self-signed SSL certificates for development-only (port is 10443)

Example:

$ ponzu run
(or)
$ ponzu run --port=8080 --https admin,api
(or) 
$ ponzu run admin
(or)
$ ponzu run --port=8888 api
(or)
$ ponzu run --dev-https

Defaults to $ ponzu run --port=8080 admin,api (running Admin & API on port 8080, without TLS)

Note: Admin and API cannot run on separate processes unless you use a copy of the database, since the first process to open it receives a lock. If you intend to run the Admin and API on separate processes, you must call them with the 'ponzu' command independently.


upgrade

Will backup your own custom project code (like content, add-ons, uploads, etc) so we can safely re-clone Ponzu from the latest version you have or from the network if necessary. Before running $ ponzu upgrade, you should update the ponzu package by running $ go get -u github.com/ponzu-cms/ponzu/...

Example:

$ ponzu upgrade

add, a

Downloads an add-on to GOPATH/src and copys it to the Ponzu project's ./addons directory. Must be called from within a Ponzu project directory.

Example:

$ ponzu add github.com/bosssauce/fbscheduler

Errors will be reported, but successful add commands return nothing.


version, v

Prints the version of Ponzu your project is using. Must be called from within a Ponzu project directory. By passing the --cli flag, the version command will print the version of the Ponzu CLI you have installed.

Example:

$ ponzu version
> Ponzu v0.8.2
(or)
$ ponzu version --cli
> Ponzu v0.9.2

Contributing

  1. Checkout branch ponzu-dev
  2. Make code changes
  3. Test changes to ponzu-dev branch
    • make a commit to ponzu-dev
    • 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)
    • build and run with $ ponzu build and $ ponzu run
  4. To add back to master:
    • first push to origin ponzu-dev
    • create a pull request
    • will then be merged into master

A typical contribution workflow might look like:

# clone the repository and checkout ponzu-dev
$ git clone https://github.com/ponzu-cms/ponzu path/to/local/ponzu # (or your fork)
$ git checkout ponzu-dev

# install ponzu with go get or from your own local path
$ go get github.com/ponzu-cms/ponzu/...
# or
$ cd /path/to/local/ponzu 
$ go install ./...

# edit files, add features, etc
$ git add -A
$ git commit -m 'edited files, added features, etc'

# now you need to test the feature.. make a new ponzu project, but pass --dev flag
$ ponzu new --dev /path/to/new/project # will create $GOPATH/src/path/to/new/project

# build & run ponzu from the new project directory
$ cd /path/to/new/project
$ ponzu build && ponzu run

# push to your origin:ponzu-dev branch and create a PR at ponzu-cms/ponzu
$ git push origin ponzu-dev
# ... go to https://github.com/ponzu-cms/ponzu and create a PR

Note: if you intend to work on your own fork and contribute from it, you will need to also pass --fork=path/to/your/fork (using OS-standard filepath structure), where path/to/your/fork must be within $GOPATH/src, and you are working from a branch called ponzu-dev.

For example:

# ($GOPATH/src is implied in the fork path, do not add it yourself)
$ ponzu new --dev --fork=github.com/nilslice/ponzu /path/to/new/project

Credits

The Go gopher was designed by Renee French. (http://reneefrench.blogspot.com) The design is licensed under the Creative Commons 3.0 Attributions license. Read this article for more details: http://blog.golang.org/gopher

The Go gopher vector illustration by Hugo Arganda @argandas (http://about.me/argandas)

"Gotoro", the sushi chef, is a modification of Hugo Arganda's illustration by Steve Manuel (https://github.com/nilslice).

Expand ▾ Collapse ▴

Directories

Path Synopsis
addons
github.com/bosssauce/reference
Package reference is a Ponzu addon to enable content editors to create references to other content types which are stored as query strings within the referencer's content DB
Package reference is a Ponzu addon to enable content editors to create references to other content types which are stored as query strings within the referencer's content DB
cmd
ponzu
Package main is located in the cmd/ponzu directory and contains the code to build and operate the command line interface (CLI) to manage Ponzu systems.
Package main is located in the cmd/ponzu directory and contains the code to build and operate the command line interface (CLI) to manage Ponzu systems.
Package content contains all user-supplied content which the system is to manage.
Package content contains all user-supplied content which the system is to manage.
examples
management
editor
Package editor enables users to create edit views from their content structs so that admins can manage content
Package editor enables users to create edit views from their content structs so that admins can manage content
format
Package format provides interfaces to format content into various kinds of data
Package format provides interfaces to format content into various kinds of data
manager
Package manager contains the admin UI to the CMS which wraps all content editor interfaces to manage the create/edit/delete capabilities of Ponzu content.
Package manager contains the admin UI to the CMS which wraps all content editor interfaces to manage the create/edit/delete capabilities of Ponzu content.
Package system contains a collection of packages that make up the internal Ponzu system, which handles addons, administration, the Admin server, the API server, analytics, databases, search, TLS, and various internal types.
Package system contains a collection of packages that make up the internal Ponzu system, which handles addons, administration, the Admin server, the API server, analytics, databases, search, TLS, and various internal types.
addon
Package addon provides an API for Ponzu addons to interface with the system
Package addon provides an API for Ponzu addons to interface with the system
admin
Package admin desrcibes the admin view containing references to various managers and editors
Package admin desrcibes the admin view containing references to various managers and editors
admin/config
Package config provides a content type to manage the Ponzu system's configuration settings for things such as its name, domain, HTTP(s) port, email, server defaults and backups.
Package config provides a content type to manage the Ponzu system's configuration settings for things such as its name, domain, HTTP(s) port, email, server defaults and backups.
admin/upload
Package upload provides a re-usable file upload and storage utility for Ponzu systems to handle multipart form data.
Package upload provides a re-usable file upload and storage utility for Ponzu systems to handle multipart form data.
admin/user
Package user contains the basic admin user creation and authentication code, specific to Ponzu systems.
Package user contains the basic admin user creation and authentication code, specific to Ponzu systems.
api
Package api sets the various API handlers which provide an HTTP interface to Ponzu content, and include the types and interfaces to enable client-side interactivity with the system.
Package api sets the various API handlers which provide an HTTP interface to Ponzu content, and include the types and interfaces to enable client-side interactivity with the system.
api/analytics
Package analytics provides the methods to run an analytics reporting system for API requests which may be useful to users for measuring access and possibly identifying bad actors abusing requests.
Package analytics provides the methods to run an analytics reporting system for API requests which may be useful to users for measuring access and possibly identifying bad actors abusing requests.
db
Package db contains all interfaces to the databases used by Ponzu, including exported functions to easily manage addons, users, indices, search, content, and configuration.
Package db contains all interfaces to the databases used by Ponzu, including exported functions to easily manage addons, users, indices, search, content, and configuration.
item
Package item provides the default functionality to Ponzu's content/data types, how they interact with the API, and how to override or enhance their abilities using various interfaces.
Package item provides the default functionality to Ponzu's content/data types, how they interact with the API, and how to override or enhance their abilities using various interfaces.
search
Package search is a wrapper around the blevesearch/bleve search indexing and query package, and provides interfaces to extend Ponzu items with rich, full-text search capability.
Package search is a wrapper around the blevesearch/bleve search indexing and query package, and provides interfaces to extend Ponzu items with rich, full-text search capability.
tls
Package tls provides the functionality to Ponzu systems to encrypt HTTP traffic through the ability to generate self-signed certificates for local development and fetch/update production certificates from Let's Encrypt.
Package tls provides the functionality to Ponzu systems to encrypt HTTP traffic through the ability to generate self-signed certificates for local development and fetch/update production certificates from Let's Encrypt.