@@ -0,0 +1,62 @@
1+# Serving web applications over HTTPS
2+
3+This short recipe shows how one can serve a servant application
4+over HTTPS, by simply using `warp-tls` instead of `warp` to provide
5+us a `run` function for running the `Application` that we get by
6+calling `serve`.
7+
8+As usual, we start by clearing our throat of a few language extensions
9+and imports.
10+
11+``` haskell
12+{-# LANGUAGE DataKinds #-}
13+{-# LANGUAGE TypeOperators #-}
14+import Network.Wai
15+import Network.Wai.Handler.Warp
16+import Network.Wai.Handler.WarpTLS
17+import Servant
18+```
19+
20+No need to work with a complicated API here, let's
21+make it as simple as it gets:
22+
23+``` haskell
24+type API = Get '[JSON] Int
25+
26+api :: Proxy API
27+api = Proxy
28+
29+server :: Server API
30+server = return 10
31+
32+app :: Application
33+app = serve api server
34+```
35+
36+It's now time to actually run the `Application`.
37+The [`warp-tls`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html)
38+package provides two functions for running an `Application`, called
39+[`runTLS`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#v:runTLS)
40+and [`runTLSSocket`](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#v:runTLSSocket).
41+We will be using the first one.
42+
43+It takes two arguments,
44+[the TLS settings](https://hackage.haskell.org/package/warp-tls-3.2.4/docs/Network-Wai-Handler-WarpTLS.html#t:TLSSettings)
45+(certificates, keys, ciphers, etc)
46+and [the warp settings](https://hackage.haskell.org/package/warp-3.2.12/docs/Network-Wai-Handler-Warp-Internal.html#t:Settings)
47+(port, logger, etc).
48+
49+We will be using very simple settings for this example but you are of
50+course invited to read the documentation for those types to find out
51+about all the knobs that you can play with.
52+
53+``` haskell
54+main :: IO ()
55+main = runTLS tlsOpts warpOpts app
56+
57+ where tlsOpts = tlsSettings "cert.pem" "secret-key.pem"
58+ warpOpts = setPort 8080 defaultSettings
59+```
60+
61+This program is available as a cabal project
62+[here](https://github.com/haskell-servant/servant/tree/master/doc/cookbook/https).