Skip to content

Commit

Permalink
go-aah/aah#178 and go-aah/aah#179 docs update for aah single binary
Browse files Browse the repository at this point in the history
  • Loading branch information
@jeevatkm
jeevatkm committed May 20, 2018
1 parent 77c0285 commit d0a5b81
Show file tree
Hide file tree
Showing 2 changed files with 82 additions and 54 deletions.
98 changes: 56 additions & 42 deletions aah-application-binary.md
View file
Original file line number Diff line number Diff line change
@@ -1,79 +1,93 @@
Title: aah Application Binary
Desc: Learn more about aah application binary internals, run flags, OS signals, cross compile build and artifact naming convention.
Keywords: aah binary, aah app binary, flags, os signals, cross compile, artifact, artifact naming
Desc: Learn about aah application binary capabilities; such as run flags, hot-reload without restart, cross compile build and artifact naming convention.
Keywords: aah binary, aah app binary, flags, hot-reload, without restart, cross compile, artifact, artifact naming
---
# Learn more about aah Application Binary
# aah Application Binary

Page describe the aah application binary artifact details.
This page describe the aah application binary capabilities and artifact details.

## Table of Contents
<div class="alert alert-info-blue">
<p><strong>Note:</strong> <code>Since v0.11.0</code> aah supports single and non-single binary build artifact packaging. It is trade off, choose it according to need.</p>
</div>

* [Input Flags](#flags)
* [Start/Stop script](#start-stop-script)
* [OS Signals](#os-signals)
### Table of Contents

* [Input Flags](#input-flags)
* [Start](#start)
* [Stop](#stop)
* [Reload](#reload)
* [Finding Embedded Files](#finding-embedded-files) <sup>for aah single binary</sup>
* [Cross Compile Build](#cross-compile-build)
* [Build Artifact Naming Convention](#build-artifact-naming-convention)

## Flags
## Input Flags

Application binary supports following input flags.

* `-version` - display the binary name, version and build date.
* `-config` - absolute path of external configuration file, it gets merge into application config before the initialize.
* `-profile` - environment profile name to activate. e.g: dev, qa, prod.
<script src="https://asciinema.org/a/kOM5GHnrMowBH6YYhTI57zfwh.js" id="asciicast-kOM5GHnrMowBH6YYhTI57zfwh" data-speed="2" data-theme="monokai" data-rows="14" async></script>

### version
## Start

`version` flag outputs the binary name, version, and build date. Also build information is available via `aah.AppBuildInfo()` method at runtime.
<span class="badge lb-sm">Since v0.11.0</span> No intermediate script to start, stop, etc.

```bash
# For e.g.: application binary name is `aahwebsite`
aahwebsite -version
To start aah application, simply use the binary input flags.

**For example**

# output
Binary Name : aahwebsite
Version : 381eaa8
Build Date : 2017-04-25T21:00:45-07:00
```bash
$ /home/aah/website/bin/aahwebsite -profile prod
```

### config
## Stop

aah application binary listens to `SIGINT` and `SIGTERM` OS signal. On receiving these signals -

Supplying external configuration file. It gets merged into application configuration before the initialize.
* application performs the graceful shutdown with timeout of `server.timeout.grace_shutdown` from `aah.conf`.
* Then aah fires the `OnShutdown` server extension event.

```bash
aahwebsite -config /etc/aahwebsite/site.conf
$ kill -TERM <process-id>

# OR

$ kill -INT <process-id>
```

### profile
## Reload

Environment profile name to active on startup.
<span class="badge lb-sm">Since v0.10.0</span> aah application binary supports `Hot-Reload` via `SIGHUP`. Basically application perform same steps as application start but reloading config, i18n, views, etc. without restart.

```bash
aahwebsite -profile qa
$ kill -HUP <process-id>
```

## Start/Stop script

aah build artifact contains two startup scripts named `aah.sh` is for `*NIX` and `aah.cmd` is for `Windows`. However you can create your own startup scripts as per your need with supported input [flags](#flags).
Application logs information similar to below-

* `*NIX` script supports `{start|stop|restart|version}`
* `Windows` script supports `{start|stop|version}`
```bash
2018-05-19 22:51:08.452 WARN aahwebsite sfo-aahweb-01 Hangup signal (SIGHUP) received
2018-05-19 22:51:08.452 INFO aahwebsite sfo-aahweb-01 Application hot-reload and reinitialization starts ...
2018-05-19 22:51:08.455 INFO aahwebsite sfo-aahweb-01 Configuration files reload succeeded
2018-05-19 22:51:08.456 INFO aahwebsite sfo-aahweb-01 Configuration values reinitialize succeeded
2018-05-19 22:51:08.456 INFO aahwebsite sfo-aahweb-01 Logging reinitialize succeeded
2018-05-19 22:51:08.456 INFO aahwebsite sfo-aahweb-01 I18n reinitialize succeeded
2018-05-19 22:51:08.457 INFO aahwebsite sfo-aahweb-01 Router reinitialize succeeded
2018-05-19 22:51:08.564 INFO aahwebsite sfo-aahweb-01 View engine reinitialize succeeded
2018-05-19 22:51:08.564 INFO aahwebsite sfo-aahweb-01 Security reinitialize succeeded
2018-05-19 22:51:08.564 INFO aahwebsite sfo-aahweb-01 Access logging reinitialize succeeded
2018-05-19 22:51:08.564 INFO aahwebsite sfo-aahweb-01 Application hot-reload and reinitialization was successful
```

Note: `start` command accepts profile and config arguments.
## Finding Embedded Files

```bash
# For e.g: `aah.sh` *NIX start script with arguments.
./aah.sh start qa
./aah.sh start qa /Users/jeeva/external-config.conf
<span class="badge lb-sm">Since v0.11.0</span> aah supports single binary build packaging.

Once the single binary is build, there would be no easy way to know which files have got embedded into the binary. In real world scenario, it is important to have some mechanism to find out the contents. It could also be helpful for developers, devops, etc.

# To stop
./aah.sh stop
```
So aah provides easy convenient input flag called `-list`. It accepts regular expression as an input and print the file/directory path which matches with given regex pattern.

## OS Signals
For regex syntax refer to https://golang.org/pkg/regexp or run `go doc regexp/syntax` on terminal.

aah application binary listens to `SIGINT` and `SIGTERM` OS signal. On receiving these signals application performs the graceful shutdown with timeout of config value `server.timeout.grace_shutdown` from `aah.conf` and then fires the `OnShutdown` server event.
<script src="https://asciinema.org/a/JOvC4imBfHy3T4OQd1iF5hdNz.js" id="asciicast-JOvC4imBfHy3T4OQd1iF5hdNz" data-speed="2" data-theme="monokai" data-rows="14" async></script>

## Cross Compile Build

Expand Down
38 changes: 26 additions & 12 deletions anatomy-aah-application.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,45 @@ Keywords: anatomy, layout, mvc, architectural, directories, aah application layo

The layout of a aah application is standardized to keep things as simple as possible and has component of MVC architectural pattern.

```cfg
### Bird's-eye View

```conf
app ⇒ Application Go source codes directory
config ⇒ Configurations files directory
└ env ⇒ Environment profile configurations directory
i18n ⇒ Internationalization and Localization message files directory
views ⇒ View Template files directory - not created for API app
static ⇒ Static public assets directory - not created for API app
logs ⇒ Logs directory (default is console on 'dev' profile)
tests ⇒ Go test source directory (upcoming), use Go standard way for unit tests
build ⇒ Application build directory
```

### Detailed View

```conf
app ⇒ Application Go source codes directory
└ controllers ⇒ Application controllers
└ models ⇒ Application business layer
└ security ⇒ Application security implementation
└ aah.go ⇒ aah application main entry point (generated code)
└ init.go ⇒ Application customization/configuration (Since v0.10)
config ⇒ Configurations files
└ init.go ⇒ Application customization/configuration (Since v0.10.0)
config ⇒ Configurations files directory
└ aah.conf ⇒ Application configuration file
└ routes.conf ⇒ Application Routes configuration file
└ security.conf ⇒ Application Security configuration file
env ⇒ Environment profile configurations
└ dev.conf ⇒ Dev - Environment profile config
└ prod.conf ⇒ Prod - Environment profile config
i18n ⇒ Internationalization and Localization message files
└ env ⇒ Environment profile configurations directory
└ dev.conf ⇒ Dev - Environment profile config
└ prod.conf ⇒ Prod - Environment profile config
i18n ⇒ Internationalization and Localization message files directory
└ messages.en ⇒ Message file
└ messages.en-US ⇒ Message file
└ messages.en-CA ⇒ Message file
views ⇒ Template files - not created for API (aah supports partial inheritance)
views ⇒ View Template files directory - not created for API
└ common ⇒ Common view template files, it can be imported to any page template
└ layouts ⇒ Application view layout files, master template for page template
└ pages ⇒ Page template files, corresponding template for controller action
static ⇒ Static public assets - not created for API
static ⇒ Static public assets directory - not created for API
└ css ⇒ CSS files
└ js ⇒ Javascript files
└ img ⇒ Image files
Expand All @@ -38,14 +54,12 @@ tests ⇒ Go test source directory (upcoming), use Go standard w
build ⇒ Application build directory
.gitignore ⇒ Typical Go .gitignore file and aah project ignore files
aah.project ⇒ aah project configuration; build config, hot-reload, etc.
app-name.pid ⇒ Application PID file (created during app startup)
app-name.pid ⇒ Application PID file (created on every app startup)
```

#### Packaged aah application will have following directories/files
```cfg
bin ⇒ Application binary under bin directory
aah.sh ⇒ *nix startup file
aah.cmd ⇒ Windows startup file
```

#### Packaged aah application won't have following directories/files
Expand Down

0 comments on commit d0a5b81

Please sign in to comment.