Merge ~ubuntu-docker-images/ubuntu-docker-images/+git/memcached:readme into ~ubuntu-docker-images/ubuntu-docker-images/+git/memcached:edge

[Lucas Kanashiro]

Improve README file of the OCI image as requested in LP #1904005

[Sergio Durigan Junior (sergiodj)]

Thanks for the MP, Lucas! I've made a few comments, but tried to keep them to a minimum. After you fix them, feel free to go ahead and merge what you have.

review: Needs Fixing

[Lucas Kanashiro (lucaskanashiro)]

Thanks Sergio! I addressed your comments and tried to clarify how authentication is working at the moment.

I am merging it now but if there is any question reach out to me.

review: Approve

diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..012f4eb
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,14 @@
+# Contributing
+
+In order to contribute to the Memcached OCI image do the following:
+
+* Create a new branch.
+* Make your changes. Keep your commits logically separated. If it is fixing a bug do not forget to mention it in the commit message.
+* Build a new image with your changes. You can use the following command:
+
+```
+$ docker build -t squeakywheel/memcached:test -f Dockerfile .
+```
+
+* Test the new image. Run it in some way that exercise your changes, you can also check th README.md file.
+* If everything goes well submit a merge proposal.
diff --git a/README.md b/README.md
index 11359a7..aeb9ed9 100644
--- a/README.md
+++ b/README.md
@@ -6,3 +6,89 @@ https://github.com/docker-library/memcached
 The only change made is installing memcached from the Ubuntu archive instead of building it from source. The Ubuntu package already supports running memcached using its CLI only (not depending on a service), so no other change was required.
 
 There is no change that should impact users.
+
+## Versions supported
+
+* `edge` = `1.5.22-2ubuntu0.2` (package from Ubuntu Focal)
+
+## Architectures supported
+
+* amd64
+* arm64
+* ppc64el
+* s390x
+
+## Usage
+
+To get this image run:
+
+```
+$ docker pull squeakywheel/memcached:edge
+```
+
+Memcached will usually work together with another app. To let them communicate you can create a docker network and then launch the memcached and the app containers:
+
+```
+$ docker network create app-net --driver bridge
+$ docker run -d --name memcached \
+                --network app-net \
+                squeakywheel/memcached:edge
+```
+
+Then run your app container with `--network app-net` and they will be able to communicate between themselves (by default `memcached` listens on port `11211`).
+
+### Environment Variables
+
+Most of the memcached configuration is done via environment variables. Some of the most used variables are the following:
+
+* `MEMCACHED_CACHE_SIZE`: determines the size of the cache, the default is `64MB`.
+* `MEMCACHED_MAX_CONNECTIONS`: determines the maximum number of concurrent connections, the default is `1024`.
+* `MEMCACHED_THREADS`: determines the number of threads to process requests, the default is `4`.
+* `MEMCACHED_PASSWORD`: define the password for the `root` user if another username is provided. By default the authentication is disabled but if this option is passed it becomes enabled.
+* `MEMCACHED_USERNAME`: define a new user. If this option is passed a password is needed to authenticate the new user.
+
+An example of how you can run memcached passing those variables:
+
+```
+$ docker run -d --name memcached \
+                --network net \
+                --env MEMCACHED_CACHE_SIZE=128 \
+                --env MEMCACHED_MAX_CONNECTIONS=2048 \
+                --env MEMCACHED_THREADS=8 \
+                --env MEMCACHED_USERNAME=john \
+                --env MEMCACHED_PASSWORD=pAs$wd \
+                squeakywheel/memcached:edge
+```
+
+There are cases where one might want to pass some memcached command line flags that are not configurable via environment variables. In this case you can pass the flags themselves or a shell script:
+
+```
+$ docker run -d --name memcached \
+                --network net \
+                squeakywheel/memcached:edge
+                <flags_or_script_with_flags>
+```
+
+### Debugging
+
+In case you need to debug what it is happening with the container you can run `docker logs <name_of_the_container>`. But if you want to get access to an interactive shell run:
+
+```
+$ docker exec -it <name_of_the_container> /bin/bash
+```
+
+To see how to use the memcached OCI image with `docker-compose` and `microk8s` check the `examples/README.md` file.
+
+## Bugs and Features request
+
+If you find a bug in our image or want to request a specific feature file a bug here:
+
+https://bugs.launchpad.net/ubuntu-server-oci/+filebug
+
+In the title of the bug add `memcached: <reason>`.
+
+Make sure to include:
+
+* The tag of the image you are using
+* Reproduction steps for the deployment
+* If it is a feature request, please provide as much detail as possible
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..d44bdb0
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,37 @@
+# Running the examples
+
+## docker-compose
+
+Install `docker-compose` from the Ubuntu archive:
+
+```
+$ sudo apt install -y docker-compose
+```
+
+Call `docker-compose` from the examples directory:
+
+```
+$ docker-compose up -d
+```
+
+Memcached will be listening on port `11211` in your host. To stop it run:
+
+```
+$ docker-compose down
+```
+
+# Microk8s
+
+With microk8s running, enable the `dns` and `storage` add-ons:
+
+```
+$ microk8s enable dns storage
+```
+
+Apply the `microk8s-deployments.yml`:
+
+```
+$ microk8s kubectl apply -f microk8s-deployments.yml
+```
+
+Memcached will be listening on port `31211` in your host.
diff --git a/examples/docker-compose.yml b/examples/docker-compose.yml
new file mode 100644
index 0000000..3149458
--- /dev/null
+++ b/examples/docker-compose.yml
@@ -0,0 +1,14 @@
+version: '2'
+
+services:
+    memcached:
+        image: squeakywheel/memcached:edge
+        network_mode: "host"
+        ports:
+            - 11211:11211
+        environment:
+            - MEMCACHED_CACHE_SIZE=128
+            - MEMCACHED_MAX_CONNECTIONS=2048
+            - MEMCACHED_THREADS=8
+            - MEMCACHED_USERNAME=john
+            - MEMCACHED_PASSWORD=pAs$wd
diff --git a/examples/microk8s-deployments.yml b/examples/microk8s-deployments.yml
new file mode 100644
index 0000000..ada3efa
--- /dev/null
+++ b/examples/microk8s-deployments.yml
@@ -0,0 +1,48 @@
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: memcached-deployment
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: memcached
+  template:
+    metadata:
+      labels:
+        app: memcached
+    spec:
+      containers:
+      - name: memcached
+        image: squeakywheel/memcached:edge
+        env:
+        - name: MEMCACHED_CACHE_SIZE
+          value: "128"
+        - name: MEMCACHED_MAX_CONNECTIONS
+          value: "2048"
+        - name: MEMCACHED_THREADS
+          value: "8"
+        - name: MEMCACHED_USERNAME
+          value: "john"
+        - name: MEMCACHED_PASSWORD
+          value: "pAs$wd"
+        ports:
+        - containerPort: 11211
+          name: memcached
+          protocol: TCP
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: memcached-service
+spec:
+  type: NodePort
+  selector:
+    app: memcached
+  ports:
+  - protocol: TCP
+    port: 11211
+    targetPort: 11211
+    nodePort: 31211
+    name: memcached