Getting Started¶
Prerequists¶
You have to install go
and have set $GOPATH
to point on a
writable directory.
You need to set $PATH
to append $GOPATH/bin
.
An example .bashrc
modification:
export GOPATH=~/goproject
export PATH=$GOPATH/bin:$PATH
After having set those variables, you must reset your shell. Restart your session or call:
source ~/.bashrc
It’s recommanded to install goimports
command that kwiscale CLI will
try to call:
go get -u golang.org/x/tools/cmd/goimports
Important: If you don’t install goimports
, kwiscale CLI may have
problem to generate a working main.go file.
Installation¶
Kwiscale is a standard Go package, so you may install it with the
go get
command.
Please, don’t use github url but use the gopkg.in url that provides versionning. , the package is at gopkg.in/kwiscale
Installation is made by the following command:
go get gopkg.in/kwiscale/framework.v1
The version v1
is the current version. To use master version, please
use v0
(while it’s not recommanded either you need a specific
feature that is not yet in next version).
At this time, kwiscale is installed and you can develop service.
You may install kwiscale cli:
go get gopkg.in/kwiscale/framework.v1/kwiscale
Right now, if you set $GOPATH/bin
in your $PATH
, the “kwiscale”
command should work:
$ kwiscale
NAME:
kwiscale - tool to manage kwiscale application
USAGE:
kwiscale [global options] command [command options] [arguments...]
VERSION:
0.0.1
COMMANDS:
new Generate resources (application, handlers...)
generate Parse configuration and generate handlers, main file...
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--project "kwiscale-app" project name, will set \
$GOPATH/src/[projectname] [$KWISCALE_PROJECT]
--handlers "handlers" handlers package name \
[$KWISCALE_HANDLERS]
--help, -h show help
--generate-bash-completion
--version, -v print the version
Basic application¶
You may create and modify application by using the kwiscale
cli or
manually.
With CLI¶
It’s recommanded to use environment variables to not repeat paths in command. To create an application named “kwiscale-tutorial”, please set this environment variable:
export KWISCALE_PROJECT=kwiscale-tutorial
Now, create application:
kwiscale new app
This command should create a directory named
$GOPATH/src/kwiscale-tutorial
.
Create a new handler to respond to the /
route that is the “index”:
kwiscale new handler index "/"
This command makes changes in $GOPATH/src/kwiscale-tutorial
:
- it appends “/” route in
config.yml
- it creates
handlers/index.go
containingIndexHandler
and register call - it creates or change
main.go
to add route to the “app”
You may now edit $GOPATH/src/kwiscale-tutorial/handlers/index.go
to
add “Get” method
package handlers
import (
"gopkg.in/kwiscale/framework.v1"
)
func init() {
kwiscale.Register(&IndexHandler{})
}
type IndexHandler struct{ kwiscale.RequestHandler }
// Add this method to serve
func (h *IndexHandler) Get() {
h.WriteString("Hello world")
}
Manually¶
With config file¶
Create a project directory
mkdir -p $GOPATH/src/kwiscale-tutorial/handlers
cd $GOPATH/src/kwiscale-tutorial
Now create config.yml
:
listen: :8000
session:
name: kwiscale-tutorial
secret: Change this to a secret passphrase
Edit ./handlers/index.go
:
package handlers
import (
"gopkg.in/kwiscale/framework.v1"
)
func init(){
kwiscale.Register(&IndexHandler{})
}
type IndexHandler struct{ kwiscale.RequestHandler }
// Add this method to serve
func (h *IndexHandler) Get() {
h.WriteString("Hello world")
}
Now, create main.go
:
package main
import (
_ "kwiscale-tutorial/handlers"
"gopkg.in/kwiscale/framework.v1"
)
func main(){
app := kwiscale.NewAppFromConfigFile()
app.ListenAndServe()
}
Note: handlers
package is imported with an underscore here. As you can see, we don’t use the package in main.go
but app
will register handlers itself. If the package is not imported, application will panic.
Without config file¶
Create a project directory
mkdir -p $GOPATH/src/kwiscale-tutorial/handlers
cd $GOPATH/src/kwiscale-tutorial
Edit ./handlers/index.go
:
package handlers
import (
"gopkg.in/kwiscale/framework.v1"
)
func init(){
// not mandatory but recommanded if you want
// to use config.yml file later to map routes.
kwiscale.Register(&IndexHandler{})
}
type IndexHandler struct{ kwiscale.RequestHandler }
// Add this method to serve
func (h *IndexHandler) Get() {
h.WriteString("Hello world")
}
Create a main.go
file:
package main
import (
"kwiscale-tutorial/handlers"
"gopkg.in/kwiscale/framework.v1"
)
func main(){
// Create a new application (nil for default configuration)
app := kwiscale.NewApp(nil)
// Add a new route
app.AddRoute("/", &handlers.IndexHandler{})
// start service
app.ListenAndServe()
}
Launch application¶
Go to the project path and launch:
go run main.go
By default, application listens ”:8000” port. You may now open a browser and go to http://127.0.0.1:8000.
The page should display “Hello you”, if not please check output on terminal
Adding routes and handlers¶
The CLI helps a lot to create handlers and routes.
But you may create handlers and routes yourself inside config.yml
file and appending your handler package file in application.
Create handler with CLI:¶
kwiscale new handler user "/user/{username:.+}"
Create handler without CLI:¶
In handlers
directory, append a new file named “user.go”
In config.yml
you have to set new route if you didn’t use CLI:
routes:
/:
handler: handlers.IndexHandler
/user/{username:.+}:
handler: handlers.UserHandler
Both CLI and manually:¶
Now append a method to respond to GET:
package handlers
import (
"gopkg.in/kwiscale/framework.v1"
)
func init(){
// Mandatory if you are using config.yml to
// map routes and handlers.
kwiscale.Register(&UserHandler{})
}
// Our new handler
type UserHandler struct { kwiscale.RequestHandler }
func (h *UserHandler) Get(){
// "username" should be present in route definition,
// see config.yml later
name := h.Vars["username"]
// write !
h.WriteString("User name:" + name)
}
As you can see, the route can take a “username” that should respect
regular expression ”.+” (at least one char). The “username” key in the
route definition will set handler.Vars["username"]
in UserHandler.
Right now, routes and handlers are defined, you may relaunch application and open http://127.0.0.1:8000/user/Foo to display “Hello Foo” in you browser.