One place for hosting & domains

      How To Host a Website with Caddy on Ubuntu 18.04


      The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program.

      Introduction

      Caddy is a web server designed around simplicity and security that comes with a number of features that are useful for hosting websites. For example, it can automatically obtain and manage TLS certificates from Let’s Encrypt to enable HTTPS, and includes support for HTTP/2. HTTPS is a system for securing traffic between your users and your server, and is quickly becoming a basic expectation of any website running in production — without it, Chrome and Firefox will warn that your website is “Not Secure” if users try to submit login information.

      Previously, the recommended method for installing Caddy was to download pre-built binaries from the Caddy project website. However, changes in how Caddy’s licensing works means that you’re no longer allowed to use these pre-built binaries for commercial purposes unless you pay a license fee, even if you’re just using Caddy internally within a business. Luckily, the Caddy source code is still fully open-source and you can build Caddy yourself to avoid running into licensing issues.

      In this tutorial, you’ll build Caddy from source and use it to host a website secured with HTTPS. This entails compiling it, configuring it using a Caddyfile and installing plugins. In the end, you’ll learn how to upgrade your installation when a new version is released.

      Prerequisites

      Step 1 — Building Caddy

      In this step, you’ll build Caddy from source with the ability to later add plugins, all without changing Caddy’s source code.

      For the purposes of this tutorial, you’ll store the source code under ~/caddy. Create that directory by running the following command:

      Navigate to it:

      You’ll store the source code for running and customizing Caddy in a file named caddy.go. Create it using the following command:

      Add the following lines:

      ~/caddy/caddy.go

      package main
      
      import (
          "github.com/caddyserver/caddy/caddy/caddymain"
      )
      
      func main() {
          // caddymain.EnableTelemetry = false
          caddymain.Run()
      }
      

      This code imports Caddy directly from Github (using Git) and starts it from the entrance main function. If you wish to enable telemetry, uncomment the caddymain.EnableTelemetry line and set the value to true. When you are done, save and close the file.

      For caddy.go to be able to use the imported dependencies, you’ll need to initialize it as a module:

      Output

      go: creating new go.mod: module caddy

      At this point, you’re all set to build the stock version of Caddy from the above source code by running:

      There will be a lot of output, detailing what libraries Go downloaded as dependencies necessary for compiling. The resulting executable is stored under $GOPATH/bin, as explained in the prerequisites.

      When it finishes, try running Caddy:

      You’ll see output similar to the following:

      Output

      Activating privacy features... done. Serving HTTP on port 2015 http://:2015 WARNING: File descriptor limit 1024 is too low for production servers. At least 8192 is recommended. Fix with `ulimit -n 8192`.

      This means that Caddy started successfully, and is available on the 2015 port. You can ignore the warning message, because that limit will be adjusted in later steps without your intervention. To exit, press CTRL + C.

      You have now built and executed Caddy. In the next step, you’ll install Caddy as a service so that it starts automatically at boot, and then adjust its ownership and permissions settings to ensure the server’s security.

      Step 2 — Installing Caddy

      Now that you’ve verified you’re able to build and run Caddy, it’s time to configure a systemd service so that Caddy can be launched automatically on system startup. To understand more about systemd, visit our Systemd Essentials tutorial.

      To begin, move the Caddy binary to /usr/local/bin, the standard location for binaries that are not managed by Ubuntu’s package manager and aren’t key to system operation:

      • sudo mv $GOPATH/bin/caddy /usr/local/bin/

      Next, change ownership of the Caddy binary over to the root user:

      • sudo chown root:root /usr/local/bin/caddy

      This will prevent other accounts from modifying the executable. However, even while the root user will own Caddy, it’s advised to execute it only using other, non-root accounts present on the system. This makes sure that in the event of Caddy (or another program) being compromised, the attacker won’t be able to modify the binary, or execute commands as root.

      Next, set the binary file’s permissions to 755 — this gives root full read/write/execute permissions for the file, while other users will only be able to read and execute it:

      • sudo chmod 755 /usr/local/bin/caddy

      Since the Caddy process will not be running as root, Linux will prevent it from binding to ports 80 and 443 (the standard ports for HTTP and HTTPS, respectively), as these are privileged operations. In order to be easily accessible at your domain, Caddy needs to be bound to one of these ports, depending on the protocol. Otherwise, you would need to add a specific port number to the domain URL in your browser to view the content it will serve.

      To allow Caddy to bind to low ports without running as root, run the following command:

      • sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy

      The setcap utility sets file capabilities. In this command it assigns the CAP_NET_BIND_SERVICE capability to the Caddy binary, which allows an executable to bind to a port lower than 1024.

      You have now finished setting up the Caddy binary, and are ready to start writing Caddy configuration. Create a directory where you’ll store Caddy’s configuration files by running the following command:

      Then, set the correct user and group permissions for it:

      • sudo chown -R root:www-data /etc/caddy

      Setting the user as root and the group as www-data ensures that Caddy will have read and write access to the folder (via the www-data group) and that only the superuser account will have the same rights to read and modify. www-data is the default user and group for web servers on Ubuntu.

      In a later step, you’ll enable automatic TLS certificate provisioning from Let’s Encrypt. In preparation for that, make a directory to store any TLS certificates that Caddy will obtain and give it the same ownership rules as the /etc/caddy directory:

      • sudo mkdir /etc/ssl/caddy
      • sudo chown -R root:www-data /etc/ssl/caddy

      Caddy must be able to write certificates to this directory and read from it in order to encrypt requests. For this reason, modify the permissions for the /etc/ssl/caddy directory so that it’s only accessible by root and www-data:

      • sudo chmod 0770 /etc/ssl/caddy

      Next, create a directory to store the files that Caddy will host:

      Then, set the directory’s owner and group to www-data:

      • sudo chown www-data:www-data /var/www

      Caddy reads its configuration from a file called Caddyfile, stored under /etc/caddy. Create the file on disk by running:

      • sudo touch /etc/caddy/Caddyfile

      To install the Caddy service, download the systemd unit file from the Caddy Github repository to /etc/systemd/system by running:

      • sudo sh -c 'curl https://raw.githubusercontent.com/caddyserver/caddy/master/dist/init/linux-systemd/caddy.service > /etc/systemd/system/caddy.service'

      Modify the service file’s permissions so it can only be modified by its owner, root:

      • sudo chmod 644 /etc/systemd/system/caddy.service

      Then, reload systemd to detect the Caddy service:

      • sudo systemctl daemon-reload

      Check whether systemd has detected the Caddy service by running systemctl status:

      • sudo systemctl status caddy

      You’ll see output similar to:

      Output

      ● caddy.service - Caddy HTTP/2 web server Loaded: loaded (/etc/systemd/system/caddy.service; disabled; vendor preset: e Active: inactive (dead) Docs: https://caddyserver.com/docs

      If you see this same output, then the new service was correctly detected by systemd.

      As part of the initial server setup prerequisite, you enabled ufw, the uncomplicated firewall, and allowed SSH connections. For Caddy to be able to serve HTTP and HTTPS traffic from your server, you’ll need to allow them in ufw by running the following command:

      • sudo ufw allow proto tcp from any to any port 80,443

      The output will be:

      Output

      Rule added Rule added (v6)

      Use ufw status to check whether your changes worked:

      You’ll see the following output:

      Output

      Status: active To Action From -- ------ ---- OpenSSH ALLOW Anywhere 80,443/tcp ALLOW Anywhere OpenSSH (v6) ALLOW Anywhere (v6) 80,443/tcp (v6) ALLOW Anywhere (v6)

      Your installation of Caddy is now complete, but it isn’t configured to serve anything. In the next step, you’ll configure Caddy to serve files from the /var/www directory.

      Step 3 — Configuring Caddy

      In this section, you’ll write basic Caddy configuration for serving static files from your server.

      Start by creating a basic HTML file in /var/www, called index.html:

      • sudo nano /var/www/index.html

      Add the following lines:

      /var/www/index.html

      <!DOCTYPE html>
      <html>
      <head>
        <title>Hello from Caddy!</title>
      </head>
      <body>
        <h1 style="font-family: sans-serif">This page is being served via Caddy</h1>
      </body>
      </html>
      

      When shown in a web browser, this file will display a heading with the text This page is being served via Caddy. Save and close the file.

      Open the Caddyfile configuration file you created earlier for editing:

      • sudo nano /etc/caddy/Caddyfile

      Add the following lines:

      /etc/caddy/Caddyfile

      :80 {
        root /var/www
        gzip
      }
      

      This is a basic Caddy config, and declares that the port 80 of your server should be served with files from /var/www and compressed using gzip to reduce page loading times on the client side.

      In a majority of cases, Caddy allows you to further customize the config directives. For instance, you can limit gzip compression to only HTML and PHP files and set the compression level to 6 (1 being the lowest and 9 being the highest) by extending the directive with curly braces and listing sub-directives underneath:

      /etc/caddy/Caddyfile

      :80 {
        root /var/www
        gzip {
            ext .html .htm .php
            level 6
        }
      }
      

      When you are done, save and close the file.

      Caddy has a huge number of different directives for many use cases. For example, the fastcgi directive could be useful for enabling PHP. The markdown directive could be used to automatically convert Markdown files to HTML before serving them, which could be useful for creating a simple blog.

      To test that everything is working correctly, start the Caddy service:

      • sudo systemctl start caddy

      Next, run systemctl status to find information about the status of the Caddy service:

      • sudo systemctl status caddy

      You’ll see the following:

      Output

      ● caddy.service - Caddy HTTP/2 web server Loaded: loaded (/etc/systemd/system/caddy.service; disabled; vendor preset: enabled) Active: active (running) since Thu 2020-03-12 11:17:49 UTC; 11s ago Docs: https://caddyserver.com/docs Main PID: 3893 (caddy) Tasks: 7 (limit: 1152) CGroup: /system.slice/caddy.service └─3893 /usr/local/bin/caddy -log stdout -log-timestamps=false -agree=true -conf=/etc/caddy/Caddyfile -root=/var/tmp Mar 12 11:17:49 caddy-article-update systemd[1]: Started Caddy HTTP/2 web server. Mar 12 11:17:49 caddy-article-update caddy[3893]: [INFO] Caddy version: v1.0.5 Mar 12 11:17:49 caddy-article-update caddy[3893]: Activating privacy features... done. Mar 12 11:17:49 caddy-article-update caddy[3893]: Serving HTTP on port 80 Mar 12 11:17:49 caddy-article-update caddy[3893]: http:// Mar 12 11:17:49 caddy-article-update caddy[3893]: [INFO] Serving http:// Mar 12 11:17:49 caddy-article-update caddy[3893]: [INFO][cache:0xc00007a7d0] Started certificate maintenance routine Mar 12 11:17:49 caddy-article-update caddy[3893]: [WARNING] Sending telemetry (attempt 1): Post "https://telemetry.caddyserver.com/v1/update/6a8159c4-3427-42 Mar 12 11:17:57 caddy-article-update caddy[3893]: [WARNING] Sending telemetry (attempt 2): Post "https://telemetry.caddyserver.com/v1/update/6a8159c4-3427-42 ...

      You can now browse to your server’s IP in a web browser. Your sample web page will display:

      Message from Caddy

      You have now configured Caddy to serve static files from your server. In the next step, you’ll extend Caddy’s functionality through the use of plugins.

      Step 4 — Using Plugins

      Plugins offer a way of changing and extending Caddy’s behavior. Generally, they offer more config directives for you to use, according to your use case. In this section, you’ll add and use plugins by installing the minify plugin, which removes excess whitespace and tidies up the code that will be sent to the client, further reducing footprint and loading times.

      The minify plugin’s GitHub repository is hacdias/caddy-minify.

      Navigate to the directory with the source code you created in step one:

      To add a plugin to Caddy, you’ll need to import it in the caddy.go file you used to build Caddy. Open caddy.go for editing:

      Import the minify plugin by adding the highlighted line, like so:

      ~/caddy/caddy.go

      package main
      
      import (
          "github.com/caddyserver/caddy/caddy/caddymain"
      
          _ "github.com/hacdias/caddy-minify"
      )
      
      func main() {
          // caddymain.EnableTelemetry = false
          caddymain.Run()
      }
      

      Save and close the file.

      Some plugins may require some slight configuration tweaks, so be sure to read the documentation for whatever ones you install. You can find a list of popular plugins in the left pane of the Caddy documentation, under Plugins.

      Any time you add a new plugin, you have to rebuild Caddy. This is because Go is a compiled programming language, meaning the source code is transformed into machine code before execution. Your change to the import declaration has altered the source code, but won’t affect the binary until it’s compiled.

      Use the go install command to compile Caddy:

      When it finishes, move the generated binary to /usr/local/bin and set up permissions for the binary like you did previously. You must take these steps every time you rebuild Caddy to ensure its functionality and security:

      • sudo mv $GOPATH/bin/caddy /usr/local/bin/
      • sudo chown root:root /usr/local/bin/caddy
      • sudo chmod 755 /usr/local/bin/caddy
      • sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy

      To start using the minify plugin, you’ll need to add the minify directive to your Caddyfile. Open it for editing:

      • sudo nano /etc/caddy/Caddyfile

      Enable the plugin by adding the following line to the configuration block:

      /etc/caddy/Caddyfile

      :80 {
        root /var/www
        gzip
        minify
      }
      

      Now, restart your server using systemctl:

      • sudo systemctl restart caddy

      Caddy is now running and will minify any files that it serves, including the index.html file you created earlier. You can observe the ‘minification’ at work by fetching the contents of your domain using curl:

      You’ll see the following output. Notice that all unnecessary whitespace has been removed, showing that the minify plugin is working.

      Output

      <!doctype html><title>Hello from Caddy!</title><h1 style=font-family:sans-serif>This page is being served via Caddy</h1>

      In this step, you learned how to extend Caddy with plugins. Next, you’ll enable HTTPS by installing the tls.dns.digitalocean plugin.

      Step 5 — Enabling Automatic TLS with Let’s Encrypt

      In this section, you’ll enable automatic Let’s Encrypt certificate provisioning and renewal, using TXT DNS records for verification.

      To verify using TXT DNS records, you’ll install a plugin for interfacing with the DigitalOcean API, called tls.dns.digitalocean. The procedure for installing it is almost identical to how you installed the minify plugin in the previous step. To begin, open caddy.go:

      Add the plugin’s repository to imports:

      ~/caddy/caddy.go

      package main
      
      import (
          "github.com/caddyserver/caddy/caddy/caddymain"
      
          _ "github.com/hacdias/caddy-minify"
      
          _ "github.com/caddyserver/dnsproviders/digitalocean"
      )
      
      func main() {
          // caddymain.EnableTelemetry = false
          caddymain.Run()
      }
      

      Compile it by running:

      Ensure Caddy is stopped via systemctl, then finish installing the plugin by copying the newly built Caddy binary and once more setting its ownership and permissions:

      • sudo systemctl stop caddy
      • sudo mv $GOPATH/bin/caddy /usr/local/bin/
      • sudo chown root:root /usr/local/bin/caddy
      • sudo chmod 755 /usr/local/bin/caddy
      • sudo setcap 'cap_net_bind_service=+ep' /usr/local/bin/caddy

      Next, configure Caddy to work with DigitalOcean’s API to set DNS records. Caddy needs to access this token as an environment variable to configure DigitalOcean’s DNS, so you’ll edit its systemd unit file:

      • sudo nano /etc/systemd/system/caddy.service

      Find the line beginning with Environment= in the [Service] section. This line defines the environment variables that should be passed to the Caddy process. Add a space at the end of this line, then add a DO_AUTH_TOKEN variable, followed by the token you just generated:

      /etc/systemd/system/caddy.service

      [Service]
      Restart=on-abnormal
      
      ; User and group the process will run as.
      User=www-data
      Group=www-data
      
      ; Letsencrypt-issued certificates will be written to this directory.
      Environment=CADDYPATH=/etc/ssl/caddy DO_AUTH_TOKEN=your_token_here
      

      Save and close this file, then reload the systemd daemon as you did earlier to ensure the configuration is updated:

      • sudo systemctl daemon-reload

      Run systemctl status to check that your configuration changes were OK:

      • sudo systemctl status caddy

      The output should look like this:

      Output

      ● caddy.service - Caddy HTTP/2 web server Loaded: loaded (/etc/systemd/system/caddy.service; disabled; vendor preset: enabled) Active: inactive (dead) Docs: https://caddyserver.com/docs ...

      You’ll need to make a couple of slight changes to your Caddyfile, so open it up for editing:

      • sudo nano /etc/caddy/Caddyfile

      Add the highlighted lines to the Caddyfile, making sure to replace your_domain with your domain (instead of just the port :80) and commenting gzip:

      /etc/caddy/Caddyfile

      your_domain {
        root /var/www
        #gzip
        minify
        tls {
            dns digitalocean
        }
      }
      

      Using a domain rather than just a port for the hostname will cause Caddy to serve requests over HTTPS. The tls directive configures Caddy’s behavior when using TLS, and the dns subdirective specifies that Caddy should use the DNS-01 system, rather than HTTP-01.

      With this, your website is ready to be deployed. Start Caddy with systemctl and then enable it, so it runs on boot:

      • sudo systemctl start caddy
      • sudo systemctl enable caddy

      If you browse to your domain, you’ll automatically be redirected to HTTPS, with the same message shown.

      Your installation of Caddy is now complete and secured, and you can further customize according to your use case.

      If you want to update Caddy when a new version comes out, you’ll need to update the go.mod file (stored in the same directory), which looks like this:

      ~/caddy/go.mod

      module caddy
      
      go 1.14
      
      require (
              github.com/caddyserver/caddy v1.0.5
              github.com/caddyserver/dnsproviders v0.4.0
              github.com/hacdias/caddy-minify v1.0.2
      )
      

      The highlighted part is the version of Caddy you are using. When a new version is released on Github (see the release tags page), you can replace the existing one in go.mod with it and compile Caddy according to the first two steps. You can do the same for all imported plugins.

      Conclusion

      You now have Caddy installed and configured on your server, serving static pages at your desired domain, secured with free Let’s Encrypt TLS certificates.

      A good next step would be to find a way of being notified when new versions of Caddy are released. For example, you could use the Atom feed for Caddy releases, or a dedicated service such as dependencies.io.

      You can explore Caddy’s documentation for more information on configuring Caddy.



      Source link

      Set Up a Reverse Proxy in an LXD Container to Host Multiple Websites


      Updated by Linode Contributed by Simos Xenitellis

      Introduction

      LXD (pronounced “Lex-Dee”) is a system container manager build on top of Linux Containers (LXC) supported by Canonical. The goal of LXD is to provide an experience similar to a virtual machine but through containerization rather than hardware virtualization. Compared to Docker for delivering applications, LXD offers nearly full operating-system functionality with additional features such as snapshots, live migrations, and storage management.

      A reverse proxy is a server that sits between internal applications and external clients, forwarding client requests to the appropriate server. While many common applications, such as Node.js, are able to function as servers on their own, they may lack a number of advanced load balancing, security, and acceleration features.

      This guide explains the creation of a reverse proxy in an LXD container in order to host multiple websites, each in their own additional containers. You will utilize NGINX and Apache web servers, while also relying on NGINX as a reverse proxy.

      Please refer to the following diagram to understand the reverse proxy created in this guide.

      Diagram of LXD reverse proxy and web servers

      In this guide you will:

      Note

      For simplicity, the term container is used throughout this guide to describe the LXD system containers.

      Before You Begin

      1. Complete A Beginner’s Guide to LXD: Setting Up an Apache Web Server In a Container. The guide instructs you to create a container called web with the Apache web server for testing purposes. Remove this container by running the following commands.

        lxc stop web
        lxc delete web
        

        Note

      2. This guide will use the hostnames apache1.example.com and nginx1.example.com for the two example websites. Replace these names with hostnames you own and setup their DNS entries to point them to the IP address of the server you created. For help with DNS see our DNS Manager Guide.

      Creating the Containers

      1. Create two containers called apache1 and nginx1, one with the Apache web server and another with the NGINX web server, respectively. For any additional websites, you may create new containers with your chosen web server software.

        lxc launch ubuntu:18.04 apache1
        lxc launch ubuntu:18.04 nginx1
        
      2. Create the proxy container for the reverse proxy.

        lxc launch ubuntu:18.04 proxy
        
      3. List the containers with the list command.

        lxc list
        
      4. The output will look similar to the following.

          
        +---------+---------+---------------------+-----------------------------------------------+------------+-----------+
        |  NAME   |  STATE  |        IPV4         |                     IPV6                      |    TYPE    | SNAPSHOTS |
        +---------+---------+---------------------+-----------------------------------------------+------------+-----------+
        | apache1 | RUNNING | 10.10.10.204 (eth0) | fd42:67a4:b462:6ae2:216:3eff:fe01:1a4e (eth0) | PERSISTENT |           |
        +---------+---------+---------------------+-----------------------------------------------+------------+-----------+
        | nginx1  | RUNNING | 10.10.10.251 (eth0) | fd42:67a4:b462:6ae2:216:3eff:febd:67e3 (eth0) | PERSISTENT |           |
        +---------+---------+---------------------+-----------------------------------------------+------------+-----------+
        | proxy   | RUNNING | 10.10.10.28 (eth0)  | fd42:67a4:b462:6ae2:216:3eff:fe00:252e (eth0) | PERSISTENT |           |
        +---------+---------+---------------------+-----------------------------------------------+------------+-----------+
        
        

        There are three containers, all in the RUNNING state – each with their own private IP address. Take note of the IP addresses (both IPv4 and IPv6) for the container proxy. You will need them to configure the proxy container in a later section.

        Now that the containers have been created, the following steps will detail how to set up the web server software in the apache1 and nginx1 containers, and the proxy container so that the web servers are accessible from the internet.

      Configuring the Apache Web Server Container

      When using a reverse proxy in front of a web server, the web server does not know the IP addresses of visitors. The web server only sees the IP address of the reverse proxy. However, each web server has a way to identify the real remote IP address of a visitor. For Apache, this is performed with the Remote IP Apache module. For the module to work, the reverse proxy must be configured to pass the remote IP address’ information.

      1. Start a shell in the apache1 container.

        lxc exec apache1 -- sudo --user ubuntu --login
        
      2. Update the package list in the apache1 container.

        sudo apt update
        
      3. Install the package apache2 in the container.

        sudo apt install -y apache2
        
      4. Create the file /etc/apache2/conf-available/remoteip.conf.

        remoteip.conf
        1
        2
        
        RemoteIPHeader X-Real-IP
        RemoteIPTrustedProxy 10.10.10.28 fd42:67a4:b462:6ae2:216:3eff:fe00:252e

        You can use the nano text editor by running the command sudo nano /etc/apache2/conf-available/remoteip.conf. Note, these are the IP addresses of the proxy container shown earlier, for both IPv4 and IPv6. Replace these with the IPs from your lxc list output.

        Note

        Instead of specifying the IP addresses, you can also use the hostname proxy.lxd. However, the RemoteIP Apache module is peculiar when using the hostname and will use only one of the two IP addresses (either IPv4 or IPv6), which means the Apache web server will not know the real source IP address for some connections. By listing explicitly both IPv4 and IPv6 addresses, you can be certain that RemoteIP will successfully accept the source IP information from all connections of the reverse proxy.

      5. Enable the new remoteip.conf configuration.

        sudo a2enconf remoteip
        
          
        Enabling conf remoteip.
        To activate the new configuration, you need to run:
        systemctl reload apache2
        
        
      6. Enable the remoteip Apache module.

        sudo a2enmod remoteip
        
          
        Enabling module remoteip.
        To activate the new configuration, you need to run:
        systemctl restart apache2
        
        
      7. Edit the default web page for Apache to make a reference that it runs inside a LXD container.

        sudo nano /var/www/html/index.html
        

        Change the line “It works!” (line number 224) to “It works inside a LXD container!” Save and exit.

      8. Restart the Apache web server.

        sudo systemctl reload apache2
        
      9. Exit back to the host.

        exit
        

      You have created and configured the Apache web server, but the server is not yet accessible from the Internet. It will become accessible after you configure the proxy container in a later section.

      Creating the NGINX Web Server Container

      Like Apache, NGINX does not know the IP addresses of visitors when using a reverse proxy in front of a web server. It only sees the IP address of the reverse proxy instead. Each NGINX web server software can identify the real remote IP address of a visitor with the Real IP module. For the module to work, the reverse proxy must be configured accordingly to pass the information regarding the remote IP addresses.

      1. Start a shell in the nginx1 container.

        lxc exec nginx1 -- sudo --user ubuntu --login
        
      2. Update the package list in the nginx1 container.

        sudo apt update
        
      3. Install NGINX in the container.

        sudo apt install -y nginx
        
      4. Create the file /etc/nginx/conf.d/real-ip.conf.

        real-ip.conf
        1
        2
        
        real_ip_header    X-Real-IP;
        set_real_ip_from  proxy.lxd;

        You can use the nano text editor by running the command sudo nano /etc/nginx/conf.d/real-ip.conf.

        Note

        You have specified the hostname of the reverse proxy, proxy.lxd. Each LXD container gets automatically a hostname, which is the name of the container plus the suffix .lxd. By specifying the set_real_ip_from field with proxy.lxd, you are instructing the NGINX web server to accept the real IP address information for each connection, as long as that connection originates from proxy.lxd. The real IP address information will be found in the HTTP header X-Real-IP in each connection.

      5. Edit the default web page for NGINX to make a reference that it runs inside a LXD container.

        sudo nano /var/www/html/index.nginx-debian.html
        

        Change the line “Welcome to nginx!” (line number 14) to “Welcome to nginx running in a LXD system container!”. Save and exit.

      6. Restart the NGINX web server.

        sudo systemctl reload nginx
        
      7. Exit back to the host.

        exit
        

      You have created and configured the NGINX web server, but the server is not accessible yet from the Internet. It will become accessible after you configure the proxy container in the next section.

      Setting up the Reverse Proxy

      In this section you will configure the container proxy. You will install NGINX and set it up as a reverse proxy, then add the appropriate LXD proxy device in order to expose both ports 80 and 443 to the internet.

      1. Add LXD proxy devices to redirect connections from the internet to ports 80 (HTTP) and 443 (HTTPS) on the server to the respective ports at the proxy container.

        lxc config device add proxy myport80 proxy listen=tcp:0.0.0.0:80 connect=tcp:127.0.0.1:80 proxy_protocol=true
        lxc config device add proxy myport443 proxy listen=tcp:0.0.0.0:443 connect=tcp:127.0.0.1:443 proxy_protocol=true
        
          
        Device myport80 added to proxy
        Device myport443 added to proxy
        
        

        The lxc config device add command takes as arguments:

        Argument Explanation
        proxy The name of the container.
        myport80 A name for this proxy device.
        proxy The type of the LXD device (LXD proxy device).
        listen=tcp:0.0.0.0:80 The proxy device will listen on the host (default) on port 80, protocol TCP, on all interfaces.
        connect=tcp:127.0.0.1:80 The proxy device will connect to the container on port 80, protocol TCP, on the loopback interface. In previous versions of LXD you could have specified localhost here. However, in LXD 3.13 or newer, you can only specify IP addresses.
        proxy_protocol=true Request to enable the PROXY protocol so that the reverse proxy will get the originating IP address from the proxy device.

        Note

        If you want to remove a proxy device, use lxc config device remove. If you want to remove the above device myport80, run the following command:

        lxc config device remove proxy myport80
        

        Where proxy is the name of the container, and myport80 is the name of the device.

      2. Start a shell in the proxy container.

        lxc exec proxy -- sudo --user ubuntu --login
        
      3. Update the package list.

        sudo apt update
        
      4. Install NGINX in the container.

        sudo apt install -y nginx
        
      5. Logout from the container.

        logout
        

      Direct Traffic to the Apache Web Server From the Reverse Proxy

      The reverse proxy container is running and the NGINX package has been installed. To work as a reverse proxy, add the appropriate website configuration so that NGINX can identify (with server_name below) the appropriate hostname, and then pass (with proxy_pass below) the connection to the appropriate LXD container.

      1. Start a shell in the proxy container.

        lxc exec proxy -- sudo --user ubuntu --login
        
      2. Create the file apache1.example.com in /etc/nginx/sites-available/ for the configuration of your first website.

        apache1.example.com
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        
        server {
                listen 80 proxy_protocol;
                listen [::]:80 proxy_protocol;
        
                server_name apache1.example.com;
        
                location / {
                        proxy_set_header Host $host;
                        proxy_set_header X-Real-IP $remote_addr;
                        proxy_pass http://apache1.lxd;
                }
        
                real_ip_header proxy_protocol;
                set_real_ip_from 127.0.0.1;
        }

        You can run sudo nano /etc/nginx/sites-available/apache1.example.com to open up a text editor and add the configuration. Note, in this case you only need to edit the server_name to be the hostname of the website.

      3. Enable the website.

        sudo ln -s /etc/nginx/sites-available/apache1.example.com /etc/nginx/sites-enabled/
        
      4. Restart the NGINX reverse proxy. By restarting the service, NGINX will read and apply the new site instructions just added to /etc/nginx/sites-enabled.

        sudo systemctl reload nginx
        
      5. Exit the proxy container and return back to the host.

        logout
        
      6. From your local computer, visit the URL of your website with your web browser. You should see the default Apache page:

        Web page of Apache server running in a container

        Note

        If you look at the Apache access.log file (default file /var/log/apache2/access.log), it will still show the private IP address of the proxy container instead of the real IP address. This issue is specific to the Apache web server and has to do with how the server prints the logs. Other software on the web server will be able to use the real IP. To fix this through the Apache logs, see the section Troubleshooting.

      Direct Traffic to the NGINX Web Server From the Reverse Proxy

      The reverse proxy container is running and the NGINX package has been installed. To work as a reverse proxy, you will add the appropriate website configuration so NGINX can identify (with server_name below) the appropriate hostname, and then pass (with proxy_pass below) the connection to the appropriate LXD container with the actual web server software.

      1. Start a shell in the proxy container.

        lxc exec proxy -- sudo --user ubuntu --login
        
      2. Create the file nginx1.example.com in /etc/nginx/sites-available/ for the configuration of your second website.

        nginx1.example.com
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        15
        
        server {
                listen 80 proxy_protocol;
                listen [::]:80 proxy_protocol;
        
                server_name nginx1.example.com;
        
                location / {
                        proxy_set_header Host $host;
                        proxy_set_header X-Real-IP $remote_addr;
                        proxy_pass http://nginx1.lxd;
                }
        
                real_ip_header proxy_protocol;
                set_real_ip_from 127.0.0.1;
        }

        You can run sudo nano /etc/nginx/sites-available/nginx1.example.com to create the configuration. Note, you only need to edit the fields server_name to be the hostname of the website.

      3. Enable the website.

        sudo ln -s /etc/nginx/sites-available/nginx1.example.com /etc/nginx/sites-enabled/
        
      4. Restart the NGINX reverse proxy service.

        sudo systemctl reload nginx
        
      5. Exit the proxy container and return back to the host.

        logout
        
      6. From your local computer, visit the URL of your website with your web browser. You should see the following default NGINX page.

        Web page of the nginx server running in a container

      Adding Support for HTTPS with Let’s Encrypt

      1. Start a shell in the proxy container.

        lxc exec proxy -- sudo --user ubuntu --login
        
      2. Add the repository ppa:certbot/certbot by running the following command.

        sudo add-apt-repository ppa:certbot/certbot
        
      3. Output will look similar to the following.

          
              This is the PPA for packages prepared by Debian Let's Encrypt Team and backported for Ubuntu(s).
              More info: https://launchpad.net/~certbot/+archive/ubuntu/certbot
             Press [ENTER] to continue or Ctrl-c to cancel adding it.
        
             Get:1 http://security.ubuntu.com/ubuntu bionic-security InRelease [88.7 kB]
             ...
             Fetched 3360 kB in 2s (2018 kB/s)
             Reading package lists... Done
        
        
      4. Install the following two packages to a) support the creation of Let’s Encrypt certificates; and b) auto-configure the NGINX reverse proxy to use Let’s Encrypt certificates. The packages are pulled from the newly-created repository.

        sudo apt-get install certbot python-certbot-nginx
        

        Note

        This configures the reverse proxy to also act as a TLS Termination Proxy. Any HTTPS configuration is only found in the proxy container. By doing so, it is not necessary to perform any tasks inside the web server containers relating to certificates and Let’s Encrypt.

      5. Run certbot as root with the --nginx parameter in order to perform the auto-configuration of Let’s Encrypt for the first website. You will be asked to supply a valid email address for urgent renewal and security notices. You will then be asked to accept the Terms of Service and whether you would like to be contacted by the Electronic Frontier Foundation in the future. Next, you will provide the website for which you are activating HTTPS. Finally, you can choose to set up a facility that automatically redirects HTTP connections to HTTPS connections.

        sudo certbot --nginx
        
          
        Saving debug log to /var/log/letsencrypt/letsencrypt.log
        Plugins selected: Authenticator nginx, Installer nginx
        Enter email address (used for urgent renewal and security notices) (Enter 'c' to
        cancel): myemail@example.com
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Please read the Terms of Service at
        https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
        agree in order to register with the ACME server at
        https://acme-v02.api.letsencrypt.org/directory
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        (A)gree/(C)ancel: A
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Would you be willing to share your email address with the Electronic Frontier
        Foundation, a founding partner of the Let's Encrypt project and the non-profit
        organization that develops Certbot? We'd like to send you email about our work
        encrypting the web, EFF news, campaigns, and ways to support digital freedom.
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        (Y)es/(N)o: N
        
        Which names would you like to activate HTTPS for?
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        1: apache1.example.com
        2: nginx1.example.com
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Select the appropriate numbers separated by commas and/or spaces, or leave input
        blank to select all options shown (Enter 'c' to cancel): 1
        Obtaining a new certificate
        Performing the following challenges:
        http-01 challenge for apache1.example.com
        Waiting for verification...
        Cleaning up challenges
        Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/apache1.example.com
        
        Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        1: No redirect - Make no further changes to the webserver configuration.
        2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
        new sites, or if you're confident your site works on HTTPS. You can undo this
        change by editing your web server's configuration.
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
        Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/apache1.example.com
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Congratulations! You have successfully enabled https://apache1.example.com
        
        You should test your configuration at:
        https://www.ssllabs.com/ssltest/analyze.html?d=apache1.example.com
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        
        IMPORTANT NOTES:
         - Congratulations! Your certificate and chain have been saved at:
           /etc/letsencrypt/live/apache1.example.com/fullchain.pem
           Your key file has been saved at:
           /etc/letsencrypt/live/apache1.example.com/privkey.pem
           Your cert will expire on 2019-10-07. To obtain a new or tweaked
           version of this certificate in the future, simply run certbot again
           with the "certonly" option. To non-interactively renew *all* of
           your certificates, run "certbot renew"
         - Your account credentials have been saved in your Certbot
           configuration directory at /etc/letsencrypt. You should make a
           secure backup of this folder now. This configuration directory will
           also contain certificates and private keys obtained by Certbot so
           making regular backups of this folder is ideal.
         - If you like Certbot, please consider supporting our work by:
        
           Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
           Donating to EFF:                    https://eff.org/donate-le
        
        
      6. Run certbot as root with the --nginx parameter in order to perform the auto-configuration of Let’s Encrypt for the second website. This is the second time we run certbot, therefore we are asked directly to select the website to configure.

        sudo certbot --nginx
        
          
        Saving debug log to /var/log/letsencrypt/letsencrypt.log
        Plugins selected: Authenticator nginx, Installer nginx
        
        Which names would you like to activate HTTPS for?
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        1: apache1.example.com
        2: nginx1.example.com
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Select the appropriate numbers separated by commas and/or spaces, or leave input
        blank to select all options shown (Enter 'c' to cancel): 2
        Obtaining a new certificate
        Performing the following challenges:
        http-01 challenge for nginx1.example.com
        Waiting for verification...
        Cleaning up challenges
        Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/nginx1.example.com
        
        Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        1: No redirect - Make no further changes to the webserver configuration.
        2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
        new sites, or if you're confident your site works on HTTPS. You can undo this
        change by editing your web server's configuration.
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
        Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/nginx1.example.com
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Congratulations! You have successfully enabled https://nginx1.example.com
        
        You should test your configuration at:
        https://www.ssllabs.com/ssltest/analyze.html?d=nginx1.example.com
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        
        IMPORTANT NOTES:
         - Congratulations! Your certificate and chain have been saved at:
           /etc/letsencrypt/live/nginx1.example.com/fullchain.pem
           Your key file has been saved at:
           /etc/letsencrypt/live/nginx1.example.com/privkey.pem
           Your cert will expire on 2019-10-07. To obtain a new or tweaked
           version of this certificate in the future, simply run certbot again
           with the "certonly" option. To non-interactively renew *all* of
           your certificates, run "certbot renew"
         - If you like Certbot, please consider supporting our work by:
        
           Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
           Donating to EFF:                    https://eff.org/donate-le
        
        
      7. After adding all websites, perform a dry run in order to test the renewal of the certificates. Check that all websites are updating successfully to ensure the automated facility will update the certificates without further effort.

        sudo certbot renew --dry-run
        
          
        Saving debug log to /var/log/letsencrypt/letsencrypt.log
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Processing /etc/letsencrypt/renewal/apache1.example.com.conf
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Cert not due for renewal, but simulating renewal for dry run
        Plugins selected: Authenticator nginx, Installer nginx
        Renewing an existing certificate
        Performing the following challenges:
        http-01 challenge for apache1.example.com
        Waiting for verification...
        Cleaning up challenges
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        new certificate deployed with reload of nginx server; fullchain is
        /etc/letsencrypt/live/apache1.example.com/fullchain.pem
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Processing /etc/letsencrypt/renewal/nginx1.example.com.conf
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Cert not due for renewal, but simulating renewal for dry run
        Plugins selected: Authenticator nginx, Installer nginx
        Renewing an existing certificate
        Performing the following challenges:
        http-01 challenge for nginx1.example.com
        Waiting for verification...
        Cleaning up challenges
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        new certificate deployed with reload of nginx server; fullchain is
        /etc/letsencrypt/live/nginx1.example.com/fullchain.pem
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        ** DRY RUN: simulating 'certbot renew' close to cert expiry
        **          (The test certificates below have not been saved.)
        
        Congratulations, all renewals succeeded. The following certs have been renewed:
          /etc/letsencrypt/live/apache1.example.com/fullchain.pem (success)
          /etc/letsencrypt/live/nginx1.example.com/fullchain.pem (success)
        ** DRY RUN: simulating 'certbot renew' close to cert expiry
        **          (The test certificates above have not been saved.)
        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        
        IMPORTANT NOTES:
         - Your account credentials have been saved in your Certbot
           configuration directory at /etc/letsencrypt. You should make a
           secure backup of this folder now. This configuration directory will
           also contain certificates and private keys obtained by Certbot so
           making regular backups of this folder is ideal.
        
        

        Note

        The certbot package adds a systemd timer in order to activate the automated renewal of Let’s Encrypt certificates. You can view the details of this timer by running systemctl list-timers.

      8. The certbot tool edits and changes the NGINX configuration files of your websites. In doing so, certbot does not obey initial listen directive (listen 80 proxy_protocol;) and does not add the proxy_protocol parameter to the newly added listen 443 ssl; lines. You must edit the configuration files for each website and append “proxy_protocol” to each “listen 443 ssl;” line.

        sudo nano /etc/nginx/sites-enabled/apache1.example.com
        sudo nano /etc/nginx/sites-enabled/nginx1.example.com
        
          
        listen 443 ssl proxy_protocol; # managed by Certbot
        listen [::]:443 ssl proxy_protocol; # managed by Certbot
        
        

        Note

        Each website configuration file has two pairs of listen directives: HTTP and HTTPS, respectively. The first is the original pair for HTTP that was added in a previous section. The second pair was added by certbot for HTTPS. These are pairs because they they cover both IPv4 and IPv6. The notation [::] refers to IPv6. When adding the parameter proxy_protocol, add it before the ; on each line as shown above.

      9. Restart NGINX.

        sudo systemctl restart nginx
        

      Troubleshooting

      Browser Error “SSL_ERROR_RX_RECORD_TOO_LONG”

      You have configured Certbot and created the appropriate Let’s Encrypt configuration for each website. But when you access the website from your browser, you get the following error.

        
      Secure Connection Failed
      
      An error occurred during a connection to apache1.example.com. SSL received a record that exceeded the maximum permissible length. Error code: SSL_ERROR_RX_RECORD_TOO_LONG
      
          The page you are trying to view cannot be shown because the authenticity of the received data could not be verified.
          Please contact the website owners to inform them of this problem.
      
      

      This error is caused when the NGINX reverse proxy in the proxy container does not have the proxy_protocol parameter in the listen 443 directives. Without the parameter, the reverse proxy does not consume the PROXY protocol information before it performs the HTTPS work. It mistakenly passes the PROXY protocol information to the HTTPS module, hence the record too long error.

      Follow the instructions in the previous section and add proxy_protocol to all listen 443 directives. Finally, restart NGINX.

      Error “Unable to connect” or “This site can’t be reached”

      When you attempt to connect to the website from your local computer and receive Unable to connect or This site can’t be reached errors, it is likely the proxy devices have not been configured.

      Run the following command on the host to verify whether LXD is listening and is able to accept connections to ports 80 (HTTP) and 443 (HTTPS).

      sudo ss -ltp '( sport = :http || sport = :https )'
      

      Note

      The ss command is similar to netstat and lsof. It shows information about network connections. In this case, we use it to verify whether there is a service on ports 80 and 443, and which service it is. * -l, to display the listening sockets, * -t, to display only TCP sockets, * -p, to show which processes use those sockets, * ( sport = :http || sport = :https ), to show only ports 80 and 443 (HTTP and HTTPS, respectively).

      In the following output we can verify that both ports 80 and 443 (HTTP and HTTPS, respectively) are in the LISTEN state. In the last column we verify that the process listening is lxd itself.

        
      State     Recv-Q  Send-Q   Local Address:Port   Peer Address:Port
      LISTEN    0       128                  *:http              *:*       users:(("lxd",pid=1301,fd=7),("lxd",pid=1301,fd=5))
      LISTEN    0       128                  *:https             *:*       users:(("lxd",pid=1349,fd=7),("lxd",pid=1349,fd=5))
      
      

      If you see a process listed other than lxd, stop that service and restart the proxy container. By restarting the proxy container, LXD will apply the proxy devices again.

      The Apache access.log Shows the IP Address of the Proxy Container

      You have set up the apache1 container and verified that it is accessible from the internet. But the logs at /var/log/apache2/access.log still show the private IP address of the proxy container, either the private IPv4 (10.x.x.x) or the private IPv6 addresses. What went wrong?

      The default log formats for printing access logs in Apache only print the IP address of the host of the last hop (i.e. the proxy server). This is the %h format specifier as shown below.

        
      LogFormat "%v:%p %h %l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" vhost_combined
      LogFormat "%h %l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" combined
      LogFormat "%h %l %u %t "%r" %>s %O" common
      
      

      The %h must be manually replaced with the %a format specifier, which prints the value as returned by the real RemoteIP Apache module.

        
      LogFormat "%v:%p %a %l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" vhost_combined
      LogFormat "%a %l %u %t "%r" %>s %O "%{Referer}i" "%{User-Agent}i"" combined
      LogFormat "%a %l %u %t "%r" %>s %O" common
      
      
      1. Run the following command in the apache1 container to edit the configuration file httpd.conf and perform the change from %h to %a.

        sudo nano /etc/apache2/apache2.conf
        
      2. Reload the Apache web server service.

        sudo systemctl reload apache2
        

      Next Steps

      You have set up a reverse proxy to host many websites on the same server and installed each website in a separate container. You can install static or dynamic websites in the containers. For dynamic websites, you may need additional configuration; check the respective documentation for setup using a reverse proxy. In addition, you may also use NGINX as a reverse proxy for non-HTTP(S) services.

      More Information

      You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

      Find answers, ask questions, and help others.

      This guide is published under a CC BY-ND 4.0 license.



      Source link

      Host a Static Site using Linode Object Storage


      Updated by Linode

      Contributed by

      Linode

      Note

      Object Storage is currently in a closed early access Beta, and you may not have access to Object Storage through the Cloud Manager or other tools. To gain access to the Early Access Program (EAP), open up a Customer Support ticket noting that you’d like to be included in the program, or e-mail objbeta@linode.com – beta access is completely free.

      Additionally, because Object Storage is in Beta, there may be breaking changes to how you access and manage Object Storage. This guide will be updated to reflect these changes if and when they occur.

      Why Host a Static Site on Object Storage?

      Static site generators are a popular solution for creating simple, fast, flexible, and attractive websites that are easy to update. You can contribute new pages and content to a static site in two steps:

      1. First, write the content for your site’s new page using Markdown, an easy-to-learn and light-weight markup language.

      2. Then, tell your static site generator to compile your Markdown (along with other relevant assets, like CSS styling, images, and JavaScript) into static HTML files.

      The second compilation step only needs to happen once for each time that you update your content. This is in contrast with a dynamic website framework like WordPress or Drupal, which will reference a relational database and compile your HTML every time a visitor loads your site.

      Benefits of Hosting on Object Storage

      Traditionally, these static HTML files would be served by a web server (like NGINX or Apache) running on a Linode. Using Object Storage to host your static site files means you do not have to worry about maintaining your site’s infrastructure. It is no longer necessary to perform typical server maintenance tasks, like software upgrades, web server configuration, and security upkeep.

      Object Storage provides an HTTP REST gateway to objects, which means a unique URL over HTTP is available for every object. Once your static site is built, making it available publicly over the Internet is as easy uploading files to an Object Storage bucket.

      Object Storage Hosting Workflow

      At a high-level, the required steps to host a static site using Object Storage are:

      1. Install the static site generator of your choice to your local computer.

      2. Create the desired content and build the site (using your static site generator).

      3. Upload the static files to your Object Storage bucket to make the content publicly available over the Internet.

      This guide will use Hugo to demonstrate how to create a static site and host it on Linode Object Storage. However, there are many other static site generators to choose from–Jekyll and Gatsby are popular choices, and the general steps outlined in this guide could be adapted to them. For more information on choosing a static site generator, see the How to Choose a Static Site Generator guide.

      Before You Begin

      1. Read the How to Use Linode Object Storage guide to familiarize yourself with Object Storage on Linode. Specifically, be sure that you have:

        • Created your Object Storage access and secret keys.
        • Installed and configure the s3cmd tool.
      2. Install and configure Git on your local computer.

      Install the Hugo Static Site Generator

      Hugo is written in Go and is known for being extremely fast to compile sites, even very large ones. It is well-supported, well-documented, and has an active community. Some useful Hugo features include shortcodes, which are an easy way to include predefined templates inside of your Markdown, and built-in LiveReload web server, which allows you to preview your site changes locally as you make them.

      1. Install Hugo on your computer:

        macOS:

        Linux/Ubuntu:

        • Determine your Linux kernel’s architecture:

          uname -r
          

          Your output will resemble the following:

            
          4.9.0-8-amd64
          
          
        • Navigate to Hugo’s GitHub releases page and download the appropriate version for your platform. This example command downloads version 0.55, but a newer release may be available:

          wget https://github.com/gohugoio/hugo/releases/download/v0.55.0/hugo_0.55.0_Linux-64bit.deb
          
        • Install the package using dpkg:

          sudo dpkg -i hugo*.deb
          
      2. Verify that Hugo is installed. You should see output indicating your installed Hugo’s version number:

        hugo version
        

      Create a Hugo Site

      In this section, you will use the Hugo CLI (command line interface) to create your Hugo site, initialize a Hugo theme, and add content to your site. Hugo’s CLI provides several useful commands for common tasks needed to build, configure, and interact with your Hugo site.

      1. Create a new Hugo site on your local computer. This command will create a folder named example-site and scaffold Hugo’s directory structure inside it:

        hugo new site example-site
        
      2. Move into your Hugo site’s root directory:

        cd example-site
        

        Note

        All commands in this section of the guide should be issued from your site’s root directory.

      3. You will use Git to add a theme to your Hugo site’s directory. Initialize your Hugo site’s directory as a Git repository:

        git init
        
      4. Install the Ananke theme as a submodule of your Hugo site’s Git repository. Git submodules allow one Git repository to be stored as a subdirectory of another Git repository, while still being able to maintain each repository’s version control information separately. The Ananke theme’s repository will be located in the ~/example-site/themes/ananke directory of your Hugo site.

        git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
        

        Note

        Hugo has many available themes that can be installed as a submodule of your Hugo site’s directory.
      5. Add the theme to your Hugo site’s configuration file. The configuration file (config.toml) is located at the root of your Hugo site’s directory.

        echo 'theme = "ananke"' >> config.toml
        
      6. Create a new content file for your site. This command will generate a Markdown file with an auto-populated date and title:

        hugo new posts/my-first-post.md
        
      7. You should see a similar output. Note that the file is located in the content/posts/ directory of your Hugo site:

          
        /home/username/example-site/content/posts/my-first-post.md created
        
        
      8. Open the Markdown file in the text editor of your choice to begin modifying its content; you can copy and paste the example snippet into your file, which contains an updated front matter section at the top and some example Markdown body text.

        Set your desired value for title. Then, set the draft state to false and add your content below the --- in Markdown syntax, if desired:

        /home/username/example-site/content/posts/my-first-post.md
         1
         2
         3
         4
         5
         6
         7
         8
         9
        10
        11
        12
        13
        14
        
        ---
        title: "My First Post"
        date: 2019-04-11T11:25:11-04:00
        draft: false
        ---
        
        # Host a Static Site on Linode Object Storage
        
        There are many benefits to using a static site generator. Here is a list of a few of them:
        
        - Run your own website without having to manage a Linode.
        - You don't need to worry about running a web server like Apache or NGINX.
        - Static website performance is typically very fast.
        - Use Git to version control your static website's content.


        About front matter

        Front matter is a collection of metadata about your content, and it is embedded at the top of your file within opening and closing --- delimiters.

        Front matter is a powerful Hugo feature that provides a mechanism for passing data that is attached to a specific piece of content to Hugo’s rendering engine. Hugo accepts front matter in TOML, YAML, and JSON formats. In the example snippet, there is YAML front matter for the title, date, and draft state of the Markdown file. These variables will be referenced and displayed by your Hugo theme.

      9. Once you have added your content, you can preview your changes by building and serving the site using Hugo’s built-in webserver:

        hugo server
        
      10. You will see a similar output:

          
        &nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp| EN
        +------------------+----+
          Pages&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp| 11
          Paginator pages&nbsp&nbsp&nbsp&nbsp|  0
          Non-page files&nbsp&nbsp&nbsp&nbsp&nbsp|  0
          Static files&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp|  3
          Processed images&nbsp&nbsp&nbsp|  0
          Aliases&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp|  1
          Sitemaps&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp|  1
          Cleaned&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp&nbsp|  0
        
        Total in 7 ms
        Watching for changes in /home/username/example-site/{content,data,layouts,static,themes}
        Watching for config changes in /home/username/example-site/config.toml
        Serving pages from memory
        Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
        Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
        Press Ctrl+C to stop
        
        
      11. The output will provide a URL to preview your site. Copy and paste the URL into a browser to access the site. In the above example Hugo’s web server URL is http://localhost:1313/.

      12. When you are happy with your site’s content you can build your site:

        hugo -v
        

        Hugo will generate your site’s static HTML files and store them in a public directory that it will create inside your project. The static files that are generated by Hugo are the files that you will upload to your Object Storage bucket to make your site accessible via the Internet.

      13. View the contents of your site’s public directory:

        ls public
        

        Your output should resemble the following example. When you built the site, the Markdown file you created and edited in steps 6 and 7 was used to generate its corresponding static HTML file in the public/posts/my-first-post/index.html directory.

          
          404.html    categories  dist        images      index.html  index.xml   posts       sitemap.xml tags
            
        


        Track your Static Site Files with Git

        It’s not necessary to version control your site files in order to host them on Object Storage, but we still recommended that you do so:

        1. Display the state of your current working directory (root of your Hugo site):

          git status
          
        2. Stage all your files to be committed:

          git add -A
          
        3. Commit all your changes and add a meaningful commit message:

          git commit -m 'Add my first post.'
          

        Once you have used Git to track your local Hugo site files, you can easily push them to a remote Git repository, like GitHub or GitLab. Storing your static site files on a remote Git repository opens up many possibilities for collaboration and automating your static site’s deployment to Linode Object Storage. To learn more about Git, see the Getting Started with Git guide.

      Upload your Static Site to Linode Object Storage

      Before proceeding with this section ensure that you have already created your Object Storage access and secret keys and have installed the s3cmd tool.

      1. Create a new Object Storage bucket; prepend s3:// to the beginning of the bucket’s name:

        s3cmd mb s3://my-bucket
        

        Note

        Buckets names must be unique within the Object Storage cluster. You might find the bucket name my-bucket is already in use by another Linode customer, in which case you will need to choose a new bucket name.

      2. Initialize your Object Storage bucket as a website. You must tell your bucket which files to serve as the index page and the error page for your static site. This is done with the --ws-index and --ws-error options:

        s3cmd ws-create --ws-index=index.html --ws-error=404.html s3://my-bucket
        

        In our Hugo example, the site’s index file is index.html and the error file is 404.html. Whenever a user visits your static site’s URL, the Object Storage service will serve the index.html page. If a site visitor tries to access an invalid path, they will be presented with the 404.html page.

      3. The command will return the following message:

          
            Bucket 's3://my-bucket/': website configuration created.
              
        
      4. Display information about your Object Storage’s website configuration to obtain your site’s URL:

        s3cmd ws-info s3://my-bucket
        
      5. You should see a similar output. Be sure to take note of your Object Storage bucket’s URL:

          
              Bucket s3://my-bucket/: Website configuration
        Website endpoint: http://website-us-east-1.linodeobjects.com/
        Index document:   index.html
        Error document:   404.html
            
        

        Note

        The Linode Object Storage early access Beta provides SSL enabled by default. This means you can access your Object Storage bucket using https, as well.

      6. Use s3cmd’s sync command to upload the contents of your static site’s public directory to your Object Storage bucket. This step will make your site available publicly on the Internet. Ensure you are in your site’s root directory on your computer (e.g. /home/username/example-site):

        s3cmd --no-mime-magic --acl-public --delete-removed --delete-after sync public/ s3://my-bucket
        
        Option                          Description
        no-mime-magic Tells Object Storage not to use file signatures when guessing the object’s MIME-type.
        acl-public Sets the access level control of the objects to public.
        delete-removed Deletes any destination objects with no corresponding source file.
        delete-after Deletes destination files that are no longer found at the source after all files are uploaded to the bucket.
      7. Use a browser to navigate to your Object Storage bucket’s URL to view your Hugo site:

        Hugo Index Page

        Note

        It may take a minute or two after your s3cmd sync completes for the page to appear at your bucket’s website URL.

      8. If needed, you can continue to update your static site locally and upload any changes using s3cmd’s sync command from step 3 of this section.

      (Optional) Next Steps

      After uploading your static site to Linode Object Storage, you may want to use a custom domain for your site. To do this, you can add a CNAME entry to your domain’s DNS records that aliases it to your Object Storage bucket’s website URL. To learn about managing DNS records on Linode, see the DNS Manager and DNS Records: An Introduction guides.

      As noted before, it’s possible to trigger automatic deployments to the Object Storage service when you push new content updates to GitHub or GitLab. This is done by leveraging a CI/CD (continuous integration/continuous delivery) tool like Travis CI. Essentially, you would build your Hugo site within the Travis environment and then run the s3cmd sync command from it to your bucket.

      More Information

      You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

      Find answers, ask questions, and help others.

      This guide is published under a CC BY-ND 4.0 license.



      Source link