From d194b2e2a4e0fedc0d5f5107df95e9a873aa6f7e Mon Sep 17 00:00:00 2001 From: "fox.cpp" Date: Mon, 3 Aug 2020 12:48:49 +0300 Subject: [PATCH] docs: Update to use Make for source builds, recommend built tarballs as a primary way --- .mkdocs.yml | 3 +- docs/tutorials/building-from-source.md | 47 +++++++++++++++++ docs/tutorials/manual-installation.md | 73 -------------------------- docs/tutorials/setting-up.md | 37 ++++++------- 4 files changed, 65 insertions(+), 95 deletions(-) create mode 100644 docs/tutorials/building-from-source.md delete mode 100644 docs/tutorials/manual-installation.md diff --git a/.mkdocs.yml b/.mkdocs.yml index 740596d..ade93c7 100644 --- a/.mkdocs.yml +++ b/.mkdocs.yml @@ -11,7 +11,7 @@ markdown_extensions: nav: - Tutorials: - tutorials/setting-up.md - - tutorials/manual-installation.md + - tutorials/building-from-source.md - tutorials/alias-to-remote.md - tutorials/multiple-domains.md - Integration with software: @@ -33,6 +33,7 @@ nav: - man/_generated_maddy-smtp.5.md - man/_generated_maddy-storage.5.md - man/_generated_maddy-targets.5.md + - man/_generated_maddy-tables.5.md - man/_generated_maddy-tls.5.md - Internals: - internals/quirks.md diff --git a/docs/tutorials/building-from-source.md b/docs/tutorials/building-from-source.md new file mode 100644 index 0000000..a71d5af --- /dev/null +++ b/docs/tutorials/building-from-source.md @@ -0,0 +1,47 @@ +# Building from source + +## System dependencies + +You need C toolchain, Go toolchain and Make: + +On Debian-based system this should work: +``` +apt-get install golang-1.14 gcc libc6-dev make +``` + +Additionally, if you want manual pages, you should also have scdoc installed. +Figuring out the appropriate way to get scdoc is left as an exercise for +reader (for Ubuntu 19.10 it is in repositories). + +## Recent Go toolchain + +maddy depends on a rather recent Go toolchain version that may not be +available in some distributions (*cough* Debian *cough*). + +It should not be hard to grab a recent built toolchain from golang.org: +``` +wget "https://dl.google.com/go/go1.14.6.linux-amd64.tar.gz" +tar xf "go1.14.6.linux-amd64.tar.gz" +export GOROOT="$PWD/go" +export PATH="$PWD/go/bin:$PATH" +``` + +## Step-by-step + +1. Clone repository +``` +git clone https://github.com/foxcpp/maddy.git +cd maddy +``` + +2. Build it +``` +make +``` + +3. Install it +``` +sudo make install +``` + +Have fun! diff --git a/docs/tutorials/manual-installation.md b/docs/tutorials/manual-installation.md deleted file mode 100644 index 0d44a90..0000000 --- a/docs/tutorials/manual-installation.md +++ /dev/null @@ -1,73 +0,0 @@ -# Manual installation & configuration - -## Dependencies - -- [Go](https://golang.org) toolchain (1.14 or newer) - - If your distribution ships an outdated Go version, you can use - following commands to get a newer version: - ``` - go get golang.org/dl/go1.14 - go1.14 download - ``` - Then use `go1.14` instead of `go` in commands below. - -- C compiler (**optional**, set CGO_ENABLED env. variable to 0 to disable) - - Required for SQLite3-based storage (default configuration) and PAM - authentication. - -## Building - -Clone maddy repo: -``` -git clone https://github.com/foxcpp/maddy.git -cd maddy -``` - -There are two binaries to build, server itself and DB management -utility. Use the following commands to install them: -``` -go build ./cmd/maddyctl -go build ./cmd/maddy -``` - -Executables will be placed in the current directory. Copy them to -/usr/local/bin or whatever directory you them to be in. - -## Configuration - -*Note*: explaination below is short and assumes that you already have -basic ideas about how email works. - -1. Install maddy and maddyctl (see above) -2. Copy maddy.conf from the repo to /etc/maddy/maddy.conf -3. Create /run/maddy and /var/lib/maddy, make sure they are writable - for the maddy user. Though, you don't have to use system directories, - see `maddy -help`. -4. Open maddy.conf with your favorite editor and change - the following: -- `tls ...` - Change to paths to TLS certificate and key. -- `$(hostname)` - Server identifier. Put your domain here if you have only one server. -- `$(primary_domain)` - Put the "main" domain you are handling messages for here. -5. Run the executable. -6. On first start-up server will generate a RSA-2048 keypair for DKIM and tell - you where file with DNS record text is placed. You need to add it to your - zone to make signing work. -7. Create user accounts you need using `maddyctl`: - ``` - maddyctl creds create foxcpp@example.org - maddyctl imap-acct create foxcpp@example.org - ``` - -Congratulations, now you have your working mail server. -IMAP endpoint is on port 993 with TLS enforced ("implicit TLS"). -SMTP endpoint is on port 465 with TLS enforced ("implicit TLS"). - -### systemd unit - -You can use the systemd unit file from the [dist/](dist) directory in -the repo to supervise the server process and start it at boot. diff --git a/docs/tutorials/setting-up.md b/docs/tutorials/setting-up.md index d3202b6..5ab4a9b 100644 --- a/docs/tutorials/setting-up.md +++ b/docs/tutorials/setting-up.md @@ -26,33 +26,28 @@ there are a few things to keep in mind: ## Installing maddy -Since there are currently no pre-compiled binaries for maddy, we are going to -build it from the source. Nothing scary, this is relatively easy to do with Go. +Your options are: -System dependencies you need to have installed is C toolchain, Git and curl. -On Debian-based distributions, this should be enough: -``` -# apt-get install gcc git curl libc6-dev -``` +* Pre-built tarball (Linux, amd64) -If you want manual pages with reference docs, install scdoc too: -``` -# apt-get install scdoc -``` + Available on [GitHub](https://github.com/foxcpp/maddy/releases) or + [foxcpp.dev](https://foxcpp.dev/maddy-builds/). -build.sh script will do the rest for you: + The tarball contains the full filesystem tree so you can directly + extract it into root directory (or you can take just executable). -``` -$ curl 'https://foxcpp.dev/maddy/build.sh' | bash -``` +* Docker image (Linux, amd64) -Alternatively, you can download the pre-built tarball from -[GitHub](https://github.com/foxcpp/maddy/releases) and extract its contents into -the root directory. + ``` + docker pull foxcpp/maddy:latest + ``` -*Note:* If you can't / don't use this script for some reason, instructions for -manual installation can be found -[here](../manual-installation) + See README at [hub.docker.com](https://hub.docker.com/r/foxcpp/maddy) + for Docker-specific instructions. + +* Building from source + + See [here](../building-from-source) for instructions. ## Host name + domain