1.\"
  2.\" Copyright (c) 2019 Ted Unangst
  3.\"
  4.\" Permission to use, copy, modify, and distribute this software for any
  5.\" purpose with or without fee is hereby granted, provided that the above
  6.\" copyright notice and this permission notice appear in all copies.
  7.\"
  8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15.\"
 16.Dd $Mdocdate$
 17.Dt HONK 8
 18.Os
 19.Sh NAME
 20.Nm honk
 21.Nd honk administration
 22.Sh DESCRIPTION
 23The
 24.Nm
 25daemon processes messages from other federated servers.
 26This is the admin manual.
 27For user operation, see
 28.Xr honk 1 .
 29.Ss SETUP
 30.Pp
 31Set up a TLS reverse proxy.
 32.Nm
 33can listen on TCP or unix sockets, but will not terminate TLS.
 34https is a required component for federation.
 35.Pp
 36Make sure to pass the Host header, if necessary (as for nginx).
 37.Bd -literal -offset indent
 38proxy_set_header Host $http_host;
 39.Ed
 40.Ss BUILD
 41Building
 42.Nm
 43requires a go compiler and libsqlite.
 44On
 45.Ox
 46this is the go and sqlite3 packages.
 47Other platforms may require additional development libraries or headers
 48to be installed.
 49Run make.
 50Please be patient.
 51Even on fast machines, building from source can take several seconds.
 52.Ss OPTIONS
 53The following options control where
 54.Nm
 55looks for data.
 56.Bl -tag -width datadirx
 57.It Fl datadir
 58The root data directory, where the database and other user data are stored.
 59Requires write access.
 60Defaults to ".".
 61.It Fl viewdir
 62The root view directory, where html and other templates are stored.
 63Read only.
 64Defaults to ".".
 65.El
 66.Ss INIT
 67Run the
 68.Ic init
 69command.
 70.Dl ./honk init
 71This will create the database and ask four questions, as well as creating
 72the initial user.
 73.Bd -literal -offset indent
 74username: (desired username)
 75password: (desired password)
 76listenaddr: (tcp or unix: localhost:31337, /var/www/honk.sock, etc.)
 77servername: (public DNS name: honk.example.com)
 78.Ed
 79.Ss OPERATION
 80Run honk.
 81.Dl date; ./honk >> log 2>&1
 82Log messages are sent to stderr and should probably be redirected to a file.
 83.Ss CUSTOMIZATION
 84Add custom memes (stickers) to the
 85.Pa memes
 86data directory.
 87Image and video files are supported.
 88.Pp
 89Add custom emus (emoji) to the
 90.Pa emus
 91data directory.
 92Image files are supported.
 93.Pp
 94Site CSS may be overridden by creating a
 95.Pa views/local.css
 96file in the data directory.
 97A restart is required after changes.
 98.Pp
 99Custom HTML messages may be added to select pages by using the
100.Ic admin
101command.
102A restart is required after changes.
103.Dl ./honk admin
104.Bl -tag -width tenletters
105.It server
106Displayed on the home page.
107.It about
108Displayed on the about page.
109.It login
110Displayed about the login form.
111.El
112.Pp
113.Ss USER ADMIN
114New users can be added with the
115.Ic adduser
116command.
117This is discouraged.
118.Dl ./honk adduser
119.Pp
120Passwords may be reset with the
121.Ic chpass
122command.
123.Dl ./honk chpass username
124.Ss MAINTENANCE
125The database may grow large over time.
126The
127.Ic cleanup
128command exists to purge old data, by default 30 days.
129This removes unreferenced, unsaved posts and attachments.
130It does not remove any original content.
131.Ss UPGRADE
132Stop the old honk process.
133.Dl pkill honk
134Backup the database.
135.Dl cp honk.db backup.db
136Perform the upgrade with the
137.Ic upgrade
138command.
139.Dl ./honk upgrade
140Restart.
141.Dl ./honk
142.Pp
143There's also a
144.Pa blob.db
145file which is important to backup and restore.
146.Pp
147The current version of the honk binary may be printed with the
148.Ic version
149command.
150.Ss SECURITY
151.Nm
152is not currently hardened against SSRF, server side request forgery.
153Be mindful of what other services may be exposed via localhost or the
154local network.
155.Ss DEBUG
156Debug mode may be enabled or disabled by running
157.Ic debug Ar on|off .
158In debug mode, secure cookies are disabled and templates are reloaded
159every request.
160.Sh FILES
161.Nm
162files are split between the data directory and the view directory.
163Both default to "." but may be specified by command line options.
164.Pp
165The data directory contains:
166.Bl -tag -width views/local.css
167.It Pa honk.db
168The main database.
169.It Pa blob.db
170Media and attachment storage.
171.It Pa emus
172Custom emoji.
173.It Pa memes
174Stickers and such.
175.It Pa views/local.css
176Locally customized CSS.
177.El
178.Pp
179The view directory contains:
180.Bl -tag -width views
181.It Pa views
182HTML templates and CSS files.
183.El
184.Sh ENVIRONMENT
185Image processing and scaling requires considerable memory.
186It is recommended to adjust the datasize ulimit to at least 1GB.
187.Sh SEE ALSO
188.Xr intro 1 ,
189.Xr honk 1
190.Sh CAVEATS
191There's no online upgrade capability.
192Upgrades may result in minutes of downtime.