Quickstart¶
This page attempts to be a quick-and-dirty guide to getting started with pgctl.
Setting up¶
The minimal setup for pgctl is a playground
directory containing the services
you want to run. A service consists of a directory with a run
script. The
script should run in the foreground.
$ cat playground/date/run
date > now.date
Once this is in place, you can start your playground and see it run.
$ pgctl start
$ pgctl log
[webapp] Serving HTTP on 0.0.0.0 port 36474 ...
$ curl
Writing Playground Services¶
pgctl
works best with a single process. When writing a run
script in
bash, use the exec
statement to replace the shell with your process. This
avoids a process tree with bash as the parent of your service. Having a single
process allows simple management of state and proper signalling for stopping
the service.
Bad: (don’t do this!)
#!/bin/bash
sleep infinity # creates a new process
Good: (do it this way!)
#!/bin/bash
exec sleep infinity # replaces the *current* process
Without the exec, stopping the service will kill bash but the sleep process
will be left behind. This kind of process-tree management is too complex for
pgctl
to auto-magically fix it for you, but it will let you know if it
becomes a problem:
$ pgctl restart
Stopping: sleeper
Stopped: sleeper
ERROR: We sent SIGTERM, but these processes did not stop:
USER PID ACCESS COMMAND
playground/sleeper: buck 2847827 f.c.. sleep
To fix this temporarily, run: pgctl stop sleeper --force
To fix it permanently, see:
http://pgctl.readthedocs.org/en/latest/user/quickstart.html#writing-playground-services
Aliases¶
With no arguments, pgctl start
is equivalent to pgctl start default
.
By default, default
maps to a list of all services.
You can configure what default
means via pgctl.yaml
:
aliases:
default:
- service1
- service2
You can also add other aliases this way. When you name an alias, it simply
expands to the list of configured services, so that pgctl start A-and-B
would be entirely equivalent to pgctl start A B
.