Getting started
Setup
Before starting with these instructions, make sure you’ve installed Edward.
To get you started with Edward, we’re going to create a few simple services and groups. Our example services will all be written in Go.
These instructions assume a bash terminal.
First off, let’s create a parent folder for our services. This is where the Edward config file will live. In your GOPATH, create a folder called edward_quickstart:
mkdir $GOPATH/edward_quickstart
If you prefer, you can also create this folder under your GitHub username, to fit in with your other projects: $GOPATH/github.com/user/edward_quickstart. The following instructions will assume $GOPATH/edward_quickstart for brevity.
Creating Your First Service
Your first service will be a classic “Hello, world!” HTTP server. This service will sit under edward_quickstart and will consist of a single file, main.go. Let’s create that directory and file now:
mkdir $GOPATH/edward_quickstart/hello
touch $GOPATH/edward_quickstart/hello/main.go
Open the main.go file you just created and add this code:
package main
import (
"flag"
"fmt"
"net/http"
)
var port = flag.Int("port", 8080, "Port number for service")
func main() {
flag.Parse()
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello, world!")
})
http.ListenAndServe(fmt.Sprintf(":%v", *port), nil)
}
This service will listen on port 8080 by default, and return “Hello, world!” in the body of every response. But we’re not going to run it quite yet, first we’re going to generate a config so we can launch this service with Edward.
Generating an Edward Config
Edward includes a generator for go services which will automatically create config
for any go services found under the current working directory. If we run edward generate
it will create a config for our new service:
cd $GOPATH/edward_quickstart/hello
edward generate
You will see a message letting you know that config for the service hello will
be generated and you will be asked to confirm. Type y
to confirm.
A file called edward.json will be created in the hello directory. You can check that hello is available as a service by listing all available services.
edward list
You should see a list that only includes the hello service.
Starting your Service
Now we have our configuration set up, we can run the hello service with this command:
edward start hello
This will build and launch the hello service. Once the command completes, open a browser and go to http://localhost:8080/, you should see the message Hello, world!.
Stopping your Service
Your service is now running in the background, you can stop it with the stop
command:
edward stop hello
If you now try to browse to http://localhost:8080/, you will see an error message, as the server is no longer running.
When running more than one service, you can stop all services at once with edward stop
.
Restarting your Service
If you’ve made changes to a service, you can restart it to trigger a rebuild. To try this out, first start the service again.
edward start hello
Now, while the service is running, open the main.go file you created earlier, and change:
fmt.Fprintf(w, "Hello, world!")
to:
fmt.Fprintf(w, "Greetings, world!")
To apply this change to your service, run the command:
edward restart hello
This will stop the service, then build and launch it again. If you browse to http://localhost:8080/ again, you will see that the message has changed to Greetings, world!.
Modifying the Edward Config
The Edward config you generated can be found at $GOPATH/edward_quickstart/edward.json. We’re going to edit this file to have the hello service listen on a different port.
Open edward.json, you will see the hello service defined as the only entry in the services array. Under commands, you will see two string values, build and launch. These define the commands used to build and launch your service, respectively.
We’re going to change the launch command to use a different port. Change:
"launch": "hello"
To:
"launch": "hello -port=8081"
Save the config file, and restart the hello service as you did earlier.
The URL http://localhost:8080/ will now no longer work, but http://localhost:8081/ will show the message as expected.
Adding a Second Service
To complement the hello service, let’s add a goodbye service. First, create a directory and source file:
mkdir $GOPATH/edward_quickstart/goodbye
touch $GOPATH/edward_quickstart/goodbye/main.go
Edit $GOPATH/edward_quickstart/goodbye/main.go and add the following code:
package main
import (
"flag"
"fmt"
"net/http"
)
var port = flag.Int("port", 8082, "Port number for service")
func main() {
flag.Parse()
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Goodbye, world!")
fmt.Println("Received request")
})
http.ListenAndServe(fmt.Sprintf(":%v", *port), nil)
}
If you run edward generate
now, it will create the goodbye service (you may be
prompted for both services, don’t worry, just confirm), but the hello service’s
config will not be changed.
Run edward list
to confirm that both services are available.
We can start our new service in the same way we started hello:
edward start goodbye
And can view the goodbye message at http://localhost:8082/.
We can also start both services at once. First, stop everything by running edward stop
.
Then run a start command specifying both services.
edward start hello goodbye
Both services will now be running. You can test at their URLs, but you can also see a summary of all your running services with:
edward status
This will show that both services are running, along with the port on which they are running, which should be 8081 for hello and 8082 for goodbye.
Creating a Group
Specifying every service you want to start can be useful for one or two services, but can get tedious for more complicated setups.
To simplify the workflow, you can create groups of services which can be started all at once from a single name.
Open your edward.json file and add a groups array as follows:
{
"groups": [
{
"name": "salutations",
"children": ["hello", "goodbye"]
}
],
"services": [
...
]
}
Save the file and you will now see salutations under the groups list when
you run edward list
.
Stop any running services, then start the group:
edward start salutations
This will build and launch both services, which you can confirm with edward status
.
Viewing Logs
For debugging, you’ll need to be able to view the output from your services. You can
follow the output from one service using the log
command.
Make sure your services are still running, and run the log command to see the output for the goodbye service:
edward log goodbye
This will begin following the output from goodbye. If you visit http://localhost:8082/,
you will see the message “Received request” in the output. You can stop following
the log by pressing Ctrl+c
to interrupt the command.
Running edward log
will show both standard and error output. You can also use
the alias edward tail
.
Summary
After this guide, you should now be able to use Edward to:
- Start, stop and restart services and groups
- Generate config for go services
- Set up groups
- View service status
- Follow service output