diff --git a/README.md b/README.md
new file mode 100644
index 0000000..24bb034
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+A simple static page service for Forgejo/Gitea.
+
+### UNIX philosophy: simple and flexible
+
+It serves static page at `http://ip:port/user/repo/path`, which can be further maniplated (SSL, caching, URL rewriting, etc.) by reverse proxies with ease.
+
+# Usage
+
+### Service setup
+
+```
+$ forgejo-pages serve -h
+Start the static page server.
+
+Usage:
+  forgejo-pages serve [flags]
+
+Flags:
+  -a, --bind string     bind address (default ":8080")
+  -b, --branch string   branch to use (default "static-pages")
+  -h, --help            help for serve
+  -s, --server string   Forgejo server address
+  -k, --token string    Forgejo api token
+
+Global Flags:
+      --config string   config file (default is $HOME/.forgejo-pages.toml)
+```
+
+Flags can be assigned through environmental variables like `PAGES_BIND`, `PAGES_BRANCH`, or config file
+
+```toml
+bind=":8080"
+server="https://git.example.com"
+token="my-secret-token"
+```
+
+Take care about permissions of the API token.
+
+### With docker
+
+```
+docker run -p 8080:8080 ronmi/forgejo-pages -s https://git.example.com -k my-secret-token
+```
+
+### Repo setup
+
+Everything in branch `static-pages` (if you have not changed it by assigning `-b` flag) will be served as-is.
+
+# FAQ
+
+### Can I use user.example.com/repo/path format?
+
+Use reverse proxy, Nginx for example:
+
+```nginx
+server {
+    server_name ~^(?<user>[^.]+)\.example\.com$;
+    location / {
+        proxy_pass http://1.2.3.4:5678/$user$uri;
+    }
+}
+```
+
+### Will it support SSL for security?
+
+No, just use reverse proxy. You might also need LetsEncrypt or Cloudflare to apply for a free SSL certificate.
+
+### Will it support caching
+
+No. It does provide very basic cache (etag, last-modified and related HTTP headers) as it just forward request to your git server. If your need more, use reverse proxy.
+
+# License
+
+MPLv2