Quickstart

Overview

This quickstart runs Vigie on your own machine with two services. It guides you through:

1. Build the vigie binary.
2. Write a configuration.
3. Start the server.
4. Query the services.
5. Change an endpoint.
6. Clean up.

It’s meant for anyone who wants to see Vigie answer before installing it on a server. It assumes you’re at ease in a terminal. How Vigie works explains the ideas behind what you run here.

Before you start

You need:

• Go, at the version of the go line of the go.mod of Vigie.
• git and curl.
• Port 8080 free on your machine.

Build the vigie binary

1. Clone the repository.

   git clone https://github.com/seagalia/vigie.git
   cd vigie

2. Build the binary.

   CGO_ENABLED=0 go build .

   The vigie binary lands in the current directory. ./vigie version prints its version.

The releases of Vigie also hold built binaries, see Install Vigie.

Write a configuration

1. Write the endpointsOne IP address and port that a service gives, with its load balancing weight. See HTTP API. of a first service in a file, one per line.

   web.txt

   # web servers
   10.0.0.5
   10.0.0.6:8081
   10.0.0.7:8080#3

   A line without a port takes the default portThe port an endpoint takes when its source gives none, set by default_port of the service. See Configuration. of the service, and #3 gives the endpoint a weight of 3. Endpoint lines describes the format.

2. Write the configuration, with the service web read from that file and the service local read from DNS. A relative path starts from the directory you run vigie in.

   config.yml

   server
   server
   Type object · Required no · Default none
   Settings of the HTTP server. A change needs a restart, a reload doesn’t apply it.:
     listen_addr
   server.listen_addr
   Type string · Required no · Default :8080
   Address the server listens on.: 127.0.0.1:8080
   services
   services
   Type list · Required yes · Default none
   Services the server answers for, at least one.:
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: web
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 8080
       file
   services[].file
   Type object · Required one source · Default none
   Reads the endpoints from a local file.:
         path
   services[].file.path
   Type path · Required yes · Default none
   File holding one endpoint line per line.: web.txt
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: local
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 9000
       dns
   services[].dns
   Type object · Required one source · Default none
   Reads the endpoints from DNS.:
         name
   services[].dns.name
   Type string · Required yes · Default none
   DNS name to look up.: localhost

3. Check the file.

   ./vigie check-config -c config.yml

   The command prints config <path> is valid, with the absolute path of the file. It also refuses the keys it doesn’t know, where serve ignores them.

Start the server

Start the server in its own terminal:

./vigie serve -c config.yml

It logs Listening with the address it listens on, and keeps running until you stop it.

Query the services

1. Ask for the endpoints of web.

   curl -s 'http://127.0.0.1:8080/services?service_name=web'

   [
     {
       "ip": "10.0.0.5",
       "port": 8080,
       "load_balancing_weight": 0
     },
     {
       "ip": "10.0.0.6",
       "port": 8081,
       "load_balancing_weight": 0
     },
     {
       "ip": "10.0.0.7",
       "port": 8080,
       "load_balancing_weight": 3
     }
   ]

2. Ask for local. It gives each address of localhost on port 9000, such as 127.0.0.1 and ::1.

   curl -s 'http://127.0.0.1:8080/services?service_name=local'

3. Open http://127.0.0.1:8080/ in a browser. The page lists both services with their endpoints, as Web page describes.

Change an endpoint

Vigie reads the file again once the answer it keeps in cache is older than 5 seconds, so a change to the endpoints needs no reloadReading the configuration file again to replace the services, on SIGHUP or POST /reload. See Reload the services..

1. Add a line to web.txt.

   echo '10.0.0.8:8080' >> web.txt

2. Wait 5 seconds, then ask for web again. The answer holds a fourth endpoint.

   curl -s 'http://127.0.0.1:8080/services?service_name=web'

A change to the configuration itself, such as a new service, needs a reload.

1. Add a third service at the end of config.yml.

   config.yml

   server
   server
   Type object · Required no · Default none
   Settings of the HTTP server. A change needs a restart, a reload doesn’t apply it.:
     listen_addr
   server.listen_addr
   Type string · Required no · Default :8080
   Address the server listens on.: 127.0.0.1:8080
   services
   services
   Type list · Required yes · Default none
   Services the server answers for, at least one.:
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: web
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 8080
       file
   services[].file
   Type object · Required one source · Default none
   Reads the endpoints from a local file.:
         path
   services[].file.path
   Type path · Required yes · Default none
   File holding one endpoint line per line.: web.txt
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: local
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 9000
       dns
   services[].dns
   Type object · Required one source · Default none
   Reads the endpoints from DNS.:
         name
   services[].dns.name
   Type string · Required yes · Default none
   DNS name to look up.: localhost
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: default
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 8080
       file
   services[].file
   Type object · Required one source · Default none
   Reads the endpoints from a local file.:
         path
   services[].file.path
   Type path · Required yes · Default none
   File holding one endpoint line per line.: web.txt

   The service named default answers the requests that give no service_name.

2. Reload the services.

   curl -s -X POST http://127.0.0.1:8080/reload

   Vigie answers services reloaded. When the new file is invalid, it answers 422 with the error and keeps the services it had.

3. Ask for the endpoints without a service name.

   curl -s http://127.0.0.1:8080/services

Clean up

Stop the server with Ctrl+C, then remove config.yml and web.txt.

Next steps

• Install Vigie on a server, as a systemd service or in a container.
• Reload the services explains SIGHUP and why to turn POST /reload off on a shared network.
• Configuration lists every key of the file.