diff --git a/README.md b/README.md
index 18f490c2..7fd0eb34 100644
--- a/README.md
+++ b/README.md
@@ -56,9 +56,11 @@ Some platforms/distros also have Oragono packages maintained for them:
 
 * Arch Linux [AUR](https://aur.archlinux.org/packages/oragono/) - Maintained by [Sean Enck (@enckse)](https://github.com/enckse).
 
-### Using Docker (BETA)
+### Using Docker
 
-A Dockerfile and docker-compose recipe are available in the [oragono-docker](https://github.com/oragono/oragono-docker) repository.
+A Dockerfile and example docker-compose recipe are available in the `distrib/docker` directory. Oragono is automatically published
+to Docker Hub at [oragono/oragono](https://hub.docker.com/r/oragono/oragono). For more information, see the distrib/docker
+[README file](https://github.com/oragono/oragono/blob/master/distrib/docker/README.md).
 
 ### From Source
 
diff --git a/distrib/docker/Dockerfile b/distrib/docker/Dockerfile
new file mode 100644
index 00000000..b3ab03fc
--- /dev/null
+++ b/distrib/docker/Dockerfile
@@ -0,0 +1,55 @@
+## build Oragono
+FROM golang:rc-alpine AS build-env
+
+RUN apk add --no-cache git make curl
+
+# copy oragono
+RUN mkdir -p /go/src/github.com/oragono/oragono
+WORKDIR /go/src/github.com/oragono/oragono
+ADD . /go/src/github.com/oragono/oragono/
+
+# make sure submodules are up-to-date
+RUN git submodule update --init
+
+# compile
+RUN make
+
+
+
+## run Oragono
+FROM alpine:3.9
+
+# metadata
+LABEL maintainer="daniel@danieloaks.net"
+LABEL description="Oragono is a modern, experimental IRC server written in Go"
+
+# install latest updates and configure alpine
+RUN apk update
+RUN apk upgrade
+RUN mkdir /lib/modules
+
+# standard ports listened on
+EXPOSE 6667/tcp 6697/tcp
+
+# oragono itself
+RUN mkdir -p /ircd-bin
+COPY --from=build-env /go/bin/oragono /ircd-bin
+COPY --from=build-env /go/src/github.com/oragono/oragono/languages /ircd-bin/languages/
+COPY --from=build-env /go/src/github.com/oragono/oragono/oragono.yaml /ircd-bin/oragono.yaml
+COPY distrib/docker/run.sh /ircd-bin/run.sh
+RUN chmod +x /ircd-bin/run.sh
+
+# running volume holding config file, db, certs
+VOLUME /ircd
+WORKDIR /ircd
+
+# default motd
+COPY --from=build-env /go/src/github.com/oragono/oragono/oragono.motd /ircd/oragono.motd
+
+# launch
+ENTRYPOINT ["/ircd-bin/run.sh"]
+
+# # uncomment to debug
+# RUN apk add --no-cache bash
+# RUN apk add --no-cache vim
+# CMD /bin/bash
diff --git a/distrib/docker/README.md b/distrib/docker/README.md
new file mode 100644
index 00000000..7ae7293b
--- /dev/null
+++ b/distrib/docker/README.md
@@ -0,0 +1,109 @@
+# Oragono Docker
+
+This folder holds Oragono's Dockerfile and related materials. Oragono
+is published iautomatically to Docker Hub at
+[oragono/oragano](https://hub.docker.com/r/oragono/oragono).
+
+The `latest` tag tracks the `stable` branch of Oragono, which contains
+the latest stable release. The `dev` tag tracks the master branch, which
+may by unstable and is not recommended for production.
+
+You can see other tags [on Docker Hub](https://hub.docker.com/r/oragono/oragono/tags)
+if you wish to run a specific version of Oragono.
+
+## Quick start
+
+The Oragono docker image is designed to work out of the box - it comes with a
+usable default config and will automatically generate self-signed TLS
+certificates. To get a working ircd, all you need to do is run the image and
+expose the ports:
+
+```shell
+docker run --name oragono -d -P oragono/oragono:tag
+```
+
+This will start Oragono and listen on ports 6667 (plain text) and 6697 (TLS).
+The first time Oragono runs it will create a config file with a randomised
+oper password. This is output to stdout, and you can view it with the docker
+logs command:
+
+```shell
+# Assuming your container is named `oragono`; use `docker container ls` to
+# find the name if you're not sure.
+docker logs oragono
+```
+
+You should see a line similar to:
+
+```
+Oper username:password is dan:cnn2tm9TP3GeI4vLaEMS
+```
+
+## Persisting data
+
+Oragono has a persistent data store, used to keep account details, channel
+registrations, and so on. To persist this data across restarts, you can mount
+a volume at /ircd.
+
+For example, to create a new docker volume and then mount it:
+
+```shell
+docker volume create oragono-data
+docker run -d -v oragono-data:/ircd -P oragono/oragono:tag
+```
+
+Or to mount a folder from your host machine:
+
+```shell
+mkdir oragono-data
+docker run -d -v $(PWD)/oragono-data:/ircd -P oragono/oragono:tag
+```
+
+## Customising the config
+
+Oragono's config file is stored at /ircd/ircd.yaml. If the file does not
+exist, the default config will be written out. You can copy the config from
+the container, edit it, and then copy it back:
+
+```shell
+# Assuming that your container is named `oragono`, as above.
+docker cp oragono:/ircd/ircd.yaml .
+vim ircd.yaml # edit the config to your liking
+docker cp ircd.yaml oragono:/ircd/ircd.yaml
+```
+
+You can use the `/rehash` command to make Oragono reload its config, or
+send it the HUP signal:
+
+```shell
+docker kill -HUP oragono
+```
+
+## Using custom TLS certificates
+
+TLS certs will by default be read from /ircd/tls.crt, with a private key
+in /ircd/tls.key. You can customise this path in the ircd.yaml file if
+you wish to mount the certificates from another volume. For information
+on using Let's Encrypt certificates, see
+[this manual entry](https://github.com/oragono/oragono/blob/master/docs/MANUAL.md#how-do-i-use-lets-encrypt-certificates).
+
+## Using docker-compose
+
+This folder contains a sample docker-compose file which can be used
+to start an Oragono instance with ports exposed and data persisted in
+a docker volume. Simply download the file and then bring it up:
+
+```shell
+curl -O https://raw.githubusercontent.com/oragono/oragono/master/distrib/docker/docker-compose.yml
+docker-compose up -d
+```
+
+## Building
+
+If you wish to manually build the docker image, you need to do so from
+the root of the Oragono repository (not the `distrib/docker` directory):
+
+```shell
+docker build -f distrib/docker/Dockerfile .
+```
+
diff --git a/distrib/docker/docker-compose.yml b/distrib/docker/docker-compose.yml
new file mode 100644
index 00000000..512e6c02
--- /dev/null
+++ b/distrib/docker/docker-compose.yml
@@ -0,0 +1,20 @@
+version: "3.2"
+
+services:
+  oragono:
+    image: oragono/oragono:latest
+    ports:
+      - "6667:6667/tcp"
+      - "6697:6697/tcp"
+    volumes:
+      - data:/ircd
+    deploy:
+      placement:
+        constraints:
+          - "node.role == manager"
+      restart_policy:
+        condition: on-failure
+      replicas: 1
+
+volumes:
+  data:
diff --git a/distrib/docker/run.sh b/distrib/docker/run.sh
new file mode 100644
index 00000000..dee4e761
--- /dev/null
+++ b/distrib/docker/run.sh
@@ -0,0 +1,29 @@
+#!/bin/sh
+
+# start in right dir
+cd /ircd
+
+# make config file
+if [ ! -f "/ircd/ircd.yaml" ]; then
+    awk '{gsub(/path: languages/,"path: /ircd-bin/languages")}1' /ircd-bin/oragono.yaml > /tmp/ircd.yaml
+
+    # change default oper passwd
+    OPERPASS=$(< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c20)
+    echo "Oper username:password is dan:$OPERPASS"
+    ENCRYPTEDPASS=$(echo "$OPERPASS" | /ircd-bin/oragono genpasswd)
+    ORIGINALPASS='\$2a\$04\$LiytCxaY0lI.guDj2pBN4eLRD5cdM2OLDwqmGAgB6M2OPirbF5Jcu'
+
+    awk "{gsub(/password: \\\"$ORIGINALPASS\\\"/,\"password: \\\"$ENCRYPTEDPASS\\\"\")}1" /tmp/ircd.yaml > /tmp/ircd2.yaml
+
+    unset OPERPASS
+    unset ENCRYPTEDPASS
+    unset ORIGINALPASS
+
+    mv /tmp/ircd2.yaml /ircd/ircd.yaml
+fi
+
+# make self-signed certs if they don't already exist
+/ircd-bin/oragono mkcerts
+
+# run!
+exec /ircd-bin/oragono run