- Unfortunately I only have time to provide very minimal support for this project at the moment.
- If you're considering using this, please realize that if you get stuck with something, onus will likely be on you to sort it out.
- As such, I do not recommend this project for production systems unless you're well equipped to diagnose problems yourself.
ABCWeb was heavily inspired by Rails for its ease-of-use, flexibility, and development speed. The goal of this project is to make developing a web app in Go just as painless. We've tried to remain as unopinionated as possible to make ABCWeb suited for many different application types, and our big selling point is the packages we've chosen, which we believe are the clear leaders in the eco-system.
Getting started is as simple as running the abcweb new
command which will
generate you a new Go web app that comes working out of the box.
You can specify extra abcweb new
command-line arguments to tell the generator
what features and packages you would like enabled.
This customizability allows abcweb to suit your requirements, whether that be a server-side rendered web app with html templates, a client-side rendered web app (react, angularjs) or a stand-alone web API server.
A lot of these features can be removed on a per-app basis by specifying
flags to the abcweb new
command.
- HTTP2 support
- Database ORM
- Database migrations
- Build system and task runner (Gulp 4)
- Automatic asset compilation on asset change
- Automatic browser refreshing with LiveReload
- Automatically rebuild Go app on code change
- Automatically run migrations against test database for testing
- SCSS and LESS support
- Asset fingerprinting, compilation, minification and gzip
- Font-Awesome and Twitter Bootstrap 4
- Infinite environments in configuration
- Command-line and environment variable configuration
- Flexible routing (stdlib context.Context)
- Flexible rendering (HTML, JSON, XML, text & binary data)
- Colored and leveled logging
- TLS1.2/SSL support
- Graceful shutdown of web server
- HTTP sessions (supports cookie, disk, memory and redis sessions)
- Flash messages
- Rendering interface to easily add support for any templating engine
- Vendored dependencies to ensure consistent compatibility
- Build command allows easy bundling & building of entire project for production deploy
- Many more features!
Databases supported: Postgres
ABCWeb uses a collection of the very best open-source projects and packages the Go community has to offer. These packages were chosen specifically because they are fast, intelligently designed, easy to use and modern. For a full list see PACKAGES.md:
mig is our fork of Goose
that patches some big issues and was tweaked to make it work better with ABCWeb. It does
everything you'd expect a migration tool to do, and has both a library and command-line component.
Mig has been bundled into the abcweb gen
and abcweb migrate
commands.
ABCSessions was designed from the ground up to make working with HTTP sessions and cookies a breeze, and it also comes with a flash messages API. ABCSessions ships with disk, memory, redis and cookie storers, and the ability to easily add new storers using our provided interfaces.
Render is a package that provides functionality for
easily rendering JSON, XML, text, binary data, and HTML templates. We have also written an interface
wrapper for Render (ABCRender) that allows you to
easily add support for any templating engine you choose if Go's html/template
is not enough for you.
Chi is one of the quickest and most modern routers in the eco-system
and is starting to gain a cult-like following. Chi was built around the context
package that was introduced
in Go 1.7. It's elegant API design and stdlib-only philosophy is what has Chi standing out from the rest.
Zap was written by Uber, and is widely regarded as the fastest and most performant logging package, even rivaling the standard library. It is a structured, leveled & colored logger.
ABCWeb comes with Cobra for handling command-line arguments and Viper for handling configuration loading. These packages are widely known, widely used and widely enjoyed.
ABCWeb uses the following dependency managers:
- Go modules
- NPM (if not skipped when generating the app)
When a project is created no versions for any software is recorded in go.mod and package.json. When you first run go
tool commands and npm install
, the required packages will be downloaded and have their versions fixed in
go.mod
and package.lock
. You should commit these files to ensure reproducible builds.
ABCWeb uses npm
for asset management (if specified when generating the app) and go mod
for Go dependency management.
When ABCWeb generates your app it also runs go mod init
to generate you a go mod file. These dependencies will
be downloaded when you run go build
or when abcweb runs that for you when you run abcweb dev
.
ABCWeb uses Gulp to handle asset compilation,
minification, task running and live reloading of the browser on changes to the asset files or
html templates. Read the Gulp section of this readme if you'd like further information.
ABCWeb also uses refresh to rebuild your go web app on changes
to your configuration or .go files. Refresh can be highly customized using the watch.toml
config file.
Read here if you're wondering why we chose a NodeJS dependency. Also note that it's optional, but highly recommended due to the conveniences it provides.
ABCWeb requires Go 1.8 or higher.
It's dead easy to generate a web app using ABCWeb.
This is required for the asset pipeline (Gulp). Using Gulp is optional (--no-gulp
),
but we highly recommend it because it makes the development process SO much easier.
# download and install abcweb
go get -u github.com/volatiletech/abcweb
# install and upgrade all dependencies (including Gulp)
abcweb deps -u
# generate your app (abcweb automatically uses the GOPATH to find your src folder)
abcweb new github.com/username/myapp
Your app has now been generated!
# cd into your new project folder
cd $GOPATH/src/github.com/username/myapp
# add your database connection details to the config file (dev and test sections)
vim config.toml
# Run abcweb dev for auto-rebuild of app, assets and LiveReload.
abcweb dev
Navigate your browser to your now running server at http://localhost:4000/,
modify your templates/main/home.html
template whilst it's running, and you should see your changes
automatically load. Awesome!
Note that changes to the .go
files or .toml
config files will automatically
rebuild your go web-server, however they will require a manual browser refresh
(automatically refreshing in the middle of server changes could put you in
a pickle, so we decided against it). Press the enter key in the terminal
running abcweb dev
to re-build and re-execute your go binary if you're
making a change that is not automatically picked up.
ABCWeb is a tool to help you scaffold and develop Go web applications.
Usage:
abcweb [command]
Available Commands:
build Builds your abcweb binary and executes the gulp build task
deps Download and optionally update all abcweb dependencies
dev Runs your abcweb app for development
dist Dist creates a distribution bundle for easy deployment
gen Generate your database models and migration files
help Help about any command
migrate Run migration tasks (up, down, redo, status, version)
new Generate a new abcweb app
test Runs the tests for your abcweb app
Flags:
-h, --help help for abcweb
--version Print the abcweb version
Use "abcweb [command] --help" for more information about a command.
This project loads configuration in the order of:
- Command line argument default values
- config.toml
- Environment variables
- Supplied command line arguments
This means that values passed into the command line will override values passed in through the config.toml and env vars.
- App configuration is found in
config.toml
. abcweb dev
Go auto-rebuild configuration is found inwatch.toml
.- Asset pipeline, task runner and build system configuration is found in
gulpfile.js
.
The API documentation can be found in the individual repos being used. I'm planning on collating them all here shortly, however for the time being you can find the documentation at their project pages. Here are links to the main ones:
- Routing: github.com/go-chi/chi
- Middleware: godoc.org/github.com/volatiletech/abcweb/abcmiddleware
- Rendering: godoc.org/github.com/volatiletech/abcweb/abcrender
- Sessions: github.com/volatiletech/abcweb/tree/master/abcsessions
- Server: godoc.org/github.com/volatiletech/abcweb/abcserver
- Logging: go.uber.org/zap/zapcore
- Loading: godoc.org/github.com/volatiletech/abcweb/abcconfig
- Command Line: github.com/spf13/cobra
- Loading: godoc.org/github.com/volatiletech/abcweb/abcdatabase
- Migrations: github.com/volatiletech/mig
Here is a brief explanation of the generated app structure. The generated comments throughout the code are also very descriptive. A video and more thorough documentation is in the process of being created:
-
main.go: Creates an app.App object which holds the configuration state for the entire app. It initializes the object and all of its members using the main.go Setup function. These members include things like the config object, the logger, the router, the renderer and so forth. Once this object is initialized, the app is executed by running the root Cobra command. The root cobra command starts the web server/listener.
-
commands.go: Sets up the cobra commands for the app, comes with a root command and a command to execute migrations so that you can run migrations on your production server and do not need to ship the abcweb binary along with it.
-
app package: App package has methods for initializing the App object mentioned above, but this is also a good place for you to put your custom app code. You can add your own objects to the App object and pass these objects around to your controllers through the routes package.
-
assets package: Where you put all of your website assets (css, fonts, imgs etc). There is also a vendor folder for vendored assets as well. The
abcweb dev
command will watch this folder and recompile these assets to a/tmp
folder, but you can also compile these assets for production using the gulp build task. Building your assets manually or for production will place them in thepublic
folder in your generated app, opposed to a/tmp
folder. -
controllers package: Where you define your Root controller struct. All of your subsequent controller structs will embed this struct so that you can access all of the necessary app state in all controllers. You can add custom objects to the parent struct, there is an example using
Main
struct in the controllers.go file. Configure these objects in the routes package. You can also create and use custom error types here. Check out the errors middleware for more info on that. -
db package: Where your generated migrations and models live, as well as any custom database code and your testdata sql file for inserting test data into the database when running
go test
. -
public folder: Assets compiled for production will be compiled into this folder.
-
rendering package: Initializes your renderer and defines your custom template helper functions.
-
routes package: Defines all of your routes, creates your controller objects and passes along the members of the App object into the controller objects. This is how your controllers get access to and manage your app state.
-
templates folder: Contains a folder for error code templates (http 401-500 by default), layout files, and the templates for each of your controllers. Comes with examples for the main controller.
-
vendor folder: Gopkg.lock and Gopkg.toml are used to configure vendoring, these are config files for the
dep
tool, which is installed when runningabcweb deps -u
. Seedep --help
. This vendor folder houses your vendored packages.
See the FAQ for installation instructions.
When ABCWeb generates your app it also includes a gulpfile.js
for you that has been written
to perform all steps of the build process incrementally. Out of the box this includes
SCSS, LESS, CSS, JS, fonts, video, images and audio. The gulpfile.js
has also been configured to
parse your CSS assets through PostCSS Autoprefixer so
CSS vendor prefixes are a thing of the past. Another reason we've included it is because it's
a Bootstrap 4 SASS dependency.
Your gulp file also comes with a watch task that can be run using abcweb dev
that will
watch all of your asset files and templates for changes, recompile them if necessary,
move them to your public assets folder and reload your browser automatically using LiveReload.
You can run this task manually using gulp watch
if desired, but it works better through abcweb dev
so you also can take advantage of the Go app rebuilding.
Once you're ready to build your assets for production, it's as simple as calling abcweb build
which will
build your Go binary for deployment and then run the gulp task called build
. This build task
will first remove all files in the public assets directory, then it will compile,
minify, gzip and fingerprint all assets and then generate a manifest.json
file
that will be loaded by your app in production mode. The assets manifest maps all of the
incoming file names to the fingerprinted asset file names, for example: {"/css/main.css": "/css/main-a2e4fe.css"}
.
Once you've finishing building your binary and assets, all you need to do is deploy your binary,
your configuration files and your public/assets
folder to your production server.
We decided to use Gulp for our build system and
task running. We realize that some people may not enjoy having a NodeJS dependency so we've
made this entirely optional (abcweb new --no-gulp
), however we highly recommend using it
due to the conveniences it provides. Unfortunately there are no robust solutions in the Go
ecosystem for this problem yet, and when we started to make our own
we quickly realized that not only would it not work effectively for a multitude of reasons,
but it would also never be as flexible and simple to use as Gulp is due to the fact
that Go is compiled and all of the existing asset tools out there are either written in or
written for Javascript. With that being said, Gulp is extremely easy to use, and ABCWeb
makes it even easier to use. Once you have NodeJS installed everything just works because
we've created a robust gulpfile for you.
Installing NodeJS is system dependant. nvm
is a popular option on some systems
but is not supported in some shells such as fish shell.
NPM comes bundled with NodeJS.
ABCWeb uses Gulp 4 as its task runner and asset build system. Once NodeJS and NPM is installed you can install Gulp using:
abcweb deps -u
if you get permission errors you can use the permissions fix described here.
The HTTP2 spec specifies that concatenating files is no longer recommended because HTTP2 supports multiplexing and retrieves files in parallel. Having them as separate files provides speed advantages.
These errors look something like: npm WARN checkPermissions Missing write access to /usr/lib/node_modules
.
Instructions for fixing this can be found here.
Bootstrap 4 dependencies (included in generated app by default):
The homepage for the ABCWeb Golang web app framework is located at: https://github.com/volatiletech/abcweb