Skip to content

Commit fd2aafc

Browse files
aldasaldas
committed
Add page describing how to start HTTP(s) server with Echo
Add anchor behind h1/h2/h2 elements to make linking easier
1 parent b27110a commit fd2aafc

File tree

8 files changed

+218
-50
lines changed

8 files changed

+218
-50
lines changed

‎cookbook/auto-tls/server.go

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
package main
22

33
import (
4+
"crypto/tls"
5+
"golang.org/x/crypto/acme"
46
"net/http"
57

68
"github.com/labstack/echo/v4"
@@ -11,7 +13,7 @@ import (
1113
func main() {
1214
e := echo.New()
1315
// e.AutoTLSManager.HostPolicy = autocert.HostWhitelist("<DOMAIN>")
14-
// Cache certificates
16+
// Cache certificates to avoid issues with rate limits (https://letsencrypt.org/docs/rate-limits)
1517
e.AutoTLSManager.Cache = autocert.DirCache("/var/www/.cache")
1618
e.Use(middleware.Recover())
1719
e.Use(middleware.Logger())
@@ -21,5 +23,38 @@ func main() {
2123
<h3>TLS certificates automatically installed from Let's Encrypt :)</h3>
2224
`)
2325
})
26+
2427
e.Logger.Fatal(e.StartAutoTLS(":443"))
2528
}
29+
30+
func customHTTPServer() {
31+
e := echo.New()
32+
e.Use(middleware.Recover())
33+
e.Use(middleware.Logger())
34+
e.GET("/", func(c echo.Context) error {
35+
return c.HTML(http.StatusOK, `
36+
<h1>Welcome to Echo!</h1>
37+
<h3>TLS certificates automatically installed from Let's Encrypt :)</h3>
38+
`)
39+
})
40+
41+
autoTLSManager := autocert.Manager{
42+
Prompt: autocert.AcceptTOS,
43+
// Cache certificates to avoid issues with rate limits (https://letsencrypt.org/docs/rate-limits)
44+
Cache: autocert.DirCache("/var/www/.cache"),
45+
//HostPolicy: autocert.HostWhitelist("<DOMAIN>"),
46+
}
47+
s := http.Server{
48+
Addr: ":443",
49+
Handler: e, // set Echo as handler
50+
TLSConfig: &tls.Config{
51+
//Certificates: nil, // <-- s.ListenAndServeTLS will populate this field
52+
GetCertificate: autoTLSManager.GetCertificate,
53+
NextProtos: []string{acme.ALPNProto},
54+
},
55+
//ReadTimeout: 30 * time.Second, // use custom timeouts
56+
}
57+
if err := s.ListenAndServeTLS("", ""); err != http.ErrServerClosed {
58+
e.Logger.Fatal(err)
59+
}
60+
}

‎website/content/cookbook/embed-resources.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,19 +6,18 @@ description = "Embed resources recipe for Echo"
66
parent = "cookbook"
77
+++
88

9-
## With go.rice
9+
## With go 1.16 embed feature
1010

1111
`server.go`
1212

13-
{{< embed "embed-resources/server.go" >}}
13+
{{< embed "embed/server.go" >}}
1414

15-
## [Source Code]({{< source "embed-resources" >}})
15+
## [Source Code]({{< source "embed" >}})
1616

17-
## With go 1.16 embed feature
17+
## With go.rice
1818

1919
`server.go`
2020

21-
{{< embed "embed/server.go" >}}
22-
23-
## [Source Code]({{< source "embed" >}})
21+
{{< embed "embed-resources/server.go" >}}
2422

23+
## [Source Code]({{< source "embed-resources" >}})

‎website/content/cookbook/http2-server-push.md

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,26 @@ e.GET("/", func(c echo.Context) (err error) {
4040

4141
If `http.Pusher` is supported, web assets are pushed; otherwise, client makes separate requests to get them.
4242

43-
### Step 4: Configure TLS server using `cert.pem` and `key.pem`
43+
### Step 4: Start TLS server using `cert.pem` and `key.pem`
4444

4545
```go
46-
e.StartTLS(":1323", "cert.pem", "key.pem")
46+
if err := e.StartTLS(":1323", "cert.pem", "key.pem"); err != http.ErrServerClosed {
47+
log.Fatal(err)
48+
}
49+
```
50+
or use customized HTTP server with your own TLSConfig
51+
```go
52+
s := http.Server{
53+
Addr: ":8443",
54+
Handler: e, // set Echo as handler
55+
TLSConfig: &tls.Config{
56+
//Certificates: nil, // <-- s.ListenAndServeTLS will populate this field
57+
},
58+
//ReadTimeout: 30 * time.Second, // use custom timeouts
59+
}
60+
if err := s.ListenAndServeTLS("cert.pem", "key.pem"); err != http.ErrServerClosed {
61+
log.Fatal(err)
62+
}
4763
```
4864

4965
### Step 5: Start the server and browse to https://localhost:1323

‎website/content/cookbook/http2.md

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,26 @@ e.GET("/request", func(c echo.Context) error {
3737
})
3838
```
3939

40-
### Step 3: Configure TLS server using `cert.pem` and `key.pem`
40+
### Step 3: Start TLS server using `cert.pem` and `key.pem`
4141

4242
```go
43-
e.StartTLS(":1323", "cert.pem", "key.pem")
43+
if err := e.StartTLS(":1323", "cert.pem", "key.pem"); err != http.ErrServerClosed {
44+
log.Fatal(err)
45+
}
46+
```
47+
or use customized HTTP server with your own TLSConfig
48+
```go
49+
s := http.Server{
50+
Addr: ":8443",
51+
Handler: e, // set Echo as handler
52+
TLSConfig: &tls.Config{
53+
//Certificates: nil, // <-- s.ListenAndServeTLS will populate this field
54+
},
55+
//ReadTimeout: 30 * time.Second, // use custom timeouts
56+
}
57+
if err := s.ListenAndServeTLS("cert.pem", "key.pem"); err != http.ErrServerClosed {
58+
log.Fatal(err)
59+
}
4460
```
4561

4662
### Step 4: Start the server and browse to https://localhost:1323/request to see the following output

‎website/content/guide/customization.md

Lines changed: 0 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -73,38 +73,6 @@ Default value is `ERROR`. Possible values:
7373
Logging is implemented using `echo.Logger` interface which allows you to register
7474
a custom logger using `Echo#Logger`.
7575

76-
## Custom Server
77-
78-
`Echo#StartServer()` can be used to run a custom server.
79-
80-
*Example*
81-
82-
```go
83-
s := &http.Server{
84-
Addr: ":1323",
85-
ReadTimeout: 20 * time.Minute,
86-
WriteTimeout: 20 * time.Minute,
87-
}
88-
e.Logger.Fatal(e.StartServer(s))
89-
```
90-
91-
## Custom HTTP/2 Cleartext Server
92-
93-
`Echo#StartH2CServer()` can be used to run a custom HTTP/2 cleartext server.
94-
95-
*Example*
96-
97-
```go
98-
import "golang.org/x/net/http2"
99-
100-
s := &http2.Server{
101-
MaxConcurrentStreams: 250,
102-
MaxReadFrameSize: 1048576,
103-
IdleTimeout: 10 * time.Second,
104-
}
105-
e.Logger.Fatal(e.StartH2CServer(":1323", s))
106-
```
107-
10876
## Startup Banner
10977

11078
`Echo#HideBanner` can be used to hide the startup banner.

‎website/content/guide/http_server.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
+++
2+
title = "Starting HTTP(S) server with Echo"
3+
description = "Serving Echo from HTTP(S) server"
4+
[menu.main]
5+
name = "HTTP(s) Server"
6+
parent = "guide"
7+
+++
8+
9+
Echo provides following convenience methods to start HTTP server with Echo as a request handler:
10+
11+
* `Echo.Start(address string)`
12+
* `Echo.StartTLS(address string, certFile, keyFile interface{})`
13+
* `Echo.StartAutoTLS(address string)`
14+
* `Echo.StartH2CServer(address string, h2s *http2.Server)`
15+
* `Echo.StartServer(s *http.Server)`
16+
17+
## HTTP Server
18+
19+
`Echo.Start` is convenience method that starts http server with Echo serving requests on port 8080.
20+
```go
21+
func main() {
22+
e := echo.New()
23+
// add middleware and routes
24+
// ...
25+
if err := e.Start(":8080"); err != http.ErrServerClosed {
26+
log.Fatal(err)
27+
}
28+
}
29+
```
30+
31+
Following is equivalent to `Echo.Start`
32+
```go
33+
func main() {
34+
e := echo.New()
35+
// add middleware and routes
36+
// ...
37+
s := http.Server{
38+
Addr: ":8080",
39+
Handler: e,
40+
//ReadTimeout: 30 * time.Second, // customize http.Server timeouts
41+
}
42+
if err := s.ListenAndServe(); err != http.ErrServerClosed {
43+
log.Fatal(err)
44+
}
45+
}
46+
```
47+
48+
## HTTPS Server
49+
50+
`Echo.StartTLS` is convenience method that starts HTTPS server with Echo serving requests on port 8443 and uses
51+
`server.crt` and `server.key` as TLS certificate pair.
52+
```go
53+
func main() {
54+
e := echo.New()
55+
// add middleware and routes
56+
// ...
57+
if err := e.StartTLS(":8443", "server.crt", "server.key"); err != http.ErrServerClosed {
58+
log.Fatal(err)
59+
}
60+
}
61+
```
62+
63+
Following is equivalent to `Echo.StartTLS`
64+
```go
65+
func main() {
66+
e := echo.New()
67+
// add middleware and routes
68+
// ...
69+
s := http.Server{
70+
Addr: ":8443",
71+
Handler: e, // set Echo as handler
72+
TLSConfig: &tls.Config{
73+
//MinVersion: 1, // customize TLS configuration
74+
},
75+
//ReadTimeout: 30 * time.Second, // use custom timeouts
76+
}
77+
if err := s.ListenAndServeTLS("server.crt", "server.key"); err != http.ErrServerClosed {
78+
log.Fatal(err)
79+
}
80+
}
81+
```
82+
83+
## Auto TLS Server with Let’s Encrypt
84+
85+
See [Auto TLS Recipe](/cooobook/auto-tls#server)
86+
87+
## HTTP/2 Cleartext Server (HTTP2 over HTTP)
88+
89+
`Echo.StartH2CServer` is convenience method that starts a custom HTTP/2 cleartext server on port 8080
90+
```go
91+
func main() {
92+
e := echo.New()
93+
// add middleware and routes
94+
// ...
95+
s := &http2.Server{
96+
MaxConcurrentStreams: 250,
97+
MaxReadFrameSize: 1048576,
98+
IdleTimeout: 10 * time.Second,
99+
}
100+
if err := e.StartH2CServer(":8080", s); err != http.ErrServerClosed {
101+
log.Fatal(err)
102+
}
103+
}
104+
```
105+
106+
Following is equivalent to `Echo.StartH2CServer`
107+
```go
108+
func main() {
109+
e := echo.New()
110+
// add middleware and routes
111+
// ...
112+
h2s := &http2.Server{
113+
MaxConcurrentStreams: 250,
114+
MaxReadFrameSize: 1048576,
115+
IdleTimeout: 10 * time.Second,
116+
}
117+
s := http.Server{
118+
Addr: ":8080",
119+
Handler: h2c.NewHandler(e, h2s),
120+
}
121+
if err := s.ListenAndServe(); err != http.ErrServerClosed {
122+
log.Fatal(err)
123+
}
124+
}
125+
```

‎website/content/guide/installation.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,34 +10,33 @@ weight = 1
1010
## Prerequisites
1111

1212
- [Install](https://golang.org/doc/install) Go
13-
- [Set](https://golang.org/doc/code.html#GOPATH) GOPATH
1413

1514
## Using [go get](https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies)
1615

1716
```sh
1817
$ cd <PROJECT IN $GOPATH>
19-
$ go get -u github.com/labstack/echo/...
18+
$ go get -u github.com/labstack/echo/v4
2019
```
2120

2221
## Using [dep](https://github.com/golang/dep)
2322

2423
```sh
2524
$ cd <PROJECT IN $GOPATH>
26-
$ dep ensure -add github.com/labstack/echo@^3.1
25+
$ dep ensure -add github.com/labstack/echo@^4.3
2726
```
2827

2928
## Using [glide](http://glide.sh)
3029

3130
```sh
3231
$ cd <PROJECT IN $GOPATH>
33-
$ glide get github.com/labstack/echo#~3.1
32+
$ glide get github.com/labstack/echo#~4.3
3433
```
3534

3635
## Using [govendor](https://github.com/kardianos/govendor)
3736

3837
```sh
3938
$ cd <PROJECT IN $GOPATH>
40-
$ govendor fetch github.com/labstack/echo@v3.1
39+
$ govendor fetch github.com/labstack/echo@v4.3
4140
```
4241

4342
Echo follows [semantic versioning](http://semver.org) managed through GitHub

‎website/layouts/_default/single.html

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,16 @@
1212
<section>
1313
{{ $url := replace .Permalink (printf "%s" .Site.BaseURL) "" }}
1414
{{ $.Scratch.Add "path" (printf "%s" .Site.BaseURL) }}
15+
<style>
16+
.hanchor {
17+
font-size: 80%;
18+
visibility: hidden;
19+
color: silver;
20+
}
21+
h1:hover a, h2:hover a, h3:hover a, h4:hover a {
22+
visibility: visible;
23+
}
24+
</style>
1525
<ul class="breadcrumb">
1626
<!-- <li><a href="/">home</a></li> -->
1727
{{ range $index, $element := split $url "/" }}
@@ -23,7 +33,7 @@
2333
{{ end }}
2434
</ul>
2535
<h1>{{ .Title }}</h1>
26-
{{ .Content }}
36+
{{ .Content | replaceRE "(<h[1-9] id=\"([^\"]+)\".+)(</h[1-9]+>)" `${1}<a href="#${2}" class="hanchor" ariaLabel="Anchor"> 🔗</a> ${3}` | safeHTML }}
2737
</section>
2838
<footer>
2939
Caught a mistake?

0 commit comments

Comments
 (0)