pgoctl.1

.\" Generated by Mmark Markdown Processer - mmark.miek.nl
.TH "PGOCTL" 1 "March 2024" "System Administration" "Docker Compose"

.SH "PGOCTL"
.SH "NAME"
.PP
pgoctl - interact remotely with pgod(8)

.SH "SYNOPSIS"
.PP
\fB\fCpgoctl [OPTION]...\fR \fIhost\fP:\fIname\fP//\fIcommands\fP

.SH "DESCRIPTION"
.PP
pgoctl is an utility to inspect and control pgod(8) managed containers remotely. The \fIhost\fP is the
machine running pgod(8), the \fIname\fP used must be the service name as configured in the configuration
for pgod(8). And the possible \fIcommands\fP are listed below.

.PP
The exit status from the docker compose is reflected in the exist status of pgoctl. Almost all
commands from docker compose are implemented. Interactive commands, like starting a shell, are not
implemented. Tailing logs is also not implemented.

.PP
The supported commands are:

.IP \(bu 4
\fB\fCup\fR run \fB\fCdocker-compose up -d\fR
.IP \(bu 4
\fB\fCdown\fR run \fB\fCdocker-compose down\fR
.IP \(bu 4
\fB\fCstop\fR run \fB\fCdocker-compose stop\fR
.IP \(bu 4
\fB\fCstart\fR run \fB\fCdocker-compose start\fR
.IP \(bu 4
\fB\fCrestart\fR run \fB\fCdocker-compose restart\fR
.IP \(bu 4
\fB\fCps\fR run \fB\fCdocker-compose ps\fR
.IP \(bu 4
\fB\fCpull\fR run \fB\fCdocker-compose pull\fR
.IP \(bu 4
\fB\fClogs\fR run \fB\fCdocker-compose logs\fR
.IP \(bu 4
\fB\fCjournal\fRrun \fB\fCjournalctl _UID=<uid>\fR - show the system logs (if any)
.IP \(bu 4
\fB\fCexec\fR run \fB\fCdocker-compose -T exec\fR - run any command in a container
.IP \(bu 4
\fB\fCload\fR load the compose file and returns errors or disallowed options
.IP \(bu 4
\fB\fCgit\fR \fBCOMMAND\fP
where \fBCOMMAND\fP can be:

.RS
.IP \(en 4
\fB\fCpull\fR, perform git pull
.IP \(en 4
\fB\fChash\fR, show current hash of repo

.RE


.PP
All command also support arguments \fB\fCpgoctl -i id_pgo -- localhost:pgo//journal --since yesterday\fR
for example.

.PP
There are only a few options:

.TP
\fB-i value\fP
identity file to use for SSH, this flag is mandatory, but if an environment variable named
"PGOCTL_ID" exists and has a value, that value will be used as the private key identity. If no
such variable exist \fB\fC-i\fR \fIis\fP mandatory.
.TP
\fB--help, -h\fP
show help
.TP
\fB--port, -p port\fP
remote port number to use (defaults to 2222)
.TP
\fB-v\fP
show version and exit


.PP
Start pgod(8) and look at some services:

.PP
.RS

.nf
% sudo cmd/pgod/pgod \-c pgo.toml \-d /tmp/pgo
[INFO ] [caddy]: Service "caddy" with upstream "https://github.com/miekg/pgo\-caddy"
[INFO ] [pgo]: Service "pgo" with upstream "https://github.com/miekg/pgo"
[INFO ] [caddy]: Launched tracking routine for "caddy"
[INFO ] [pgo]: Launched tracking routine for "pgo"
[INFO ] Launched server on port :9112 (prometheus)
[INFO ] Launched server on port :2222 (ssh) with 2 services tracked
[WARN ] [caddy]: Failed to get public keys: open /tmp/pgo/caddy/ssh: no such file or directory
[INFO ] [caddy]: Checked out git repo in /tmp/pgo/caddy for "caddy" (branch main) with 0 configured public keys
[INFO ] [caddy]: Writing Caddy import file "caddy/Caddyfile\-import"
[INFO ] [pgo]: Checked out git repo in /tmp/pgo/pgo for "pgo" (branch main) with 3 configured public keys
[INFO ] [caddy]: Pulling containers
[INFO ] [pgo]: Pulling containers
[INFO ] [caddy]: Upping services
[INFO ] [pgo]: Upping services
[INFO ] [caddy]: Tracking upstream
[INFO ] [pgo]: Tracking upstream

.fi
.RE

.PP
Then up the services, if not done already:

.PP
.RS

.nf
% cmd/pgoctl/pgoctl \-i ssh/id\_pgo localhost:pgo//up
Container pgo\-frontend\-1  Running

.fi
.RE

.PP
Looking at the \fB\fCps\fR:

.PP
.RS

.nf
% cmd/pgoctl/pgoctl \-i ssh/id\_pgo localhost:pgo//ps
NAME                IMAGE               COMMAND                  SERVICE             CREATED             STATUS              PORTS
pgo\-frontend\-1      docker.io/busybox   "/bin/busybox httpd …"   frontend            14 minutes ago      Up 14 minutes       0.0.0.0:32771\->8080/tcp

.fi
.RE

.PP
Or \fB\fCexec\fR inside a container/service. Docker compose expects the service to be used here, this is the
service \fIas specfied in the compose.yaml\fP.

.PP
.RS

.nf
% cmd/pgoctl/pgoctl \-i id\_pgo \-\- localhost:pgo//exec frontend /bin/ls
bin    etc    lib    proc   run    tmp    var
dev    home   lib64  root   sys    usr

.fi
.RE

.SH "BUGS"
.PP
Streaming responses are not implemented, i.e tailing a service log is currently not possible.

.SH "ALSO SEE"
.PP
See this design doc
\[la]https://miek.nl/2022/november/15/provisioning-services/\[ra], and
gitopper
\[la]https://github.com/miekg/gitopper\[ra]. And see pgod(8) docker(1).