NGINX Static Server - ghomem/legacy_puppet_infrastructure GitHub Wiki

NGINX Static Server

We have a class called nginx_static and a defined type called nginx_static_domain.
They're almost identical, the most important difference is that the class nginx_static removes the nginx default configuration, so you'll probably always want to use one class. That means, if you have one server, you'll probably want to use the class. If you want ten servers, you'll probably want use the class one time and the defined type nine times.
The other differences are only on default values, the reason for this decision was to keep a similar usability to nginx_frontend and nginx_frontend_domain.

The static servers can be used in conjunction with the frontends.
If you do intend to do that, you can use the nginx_static class combined with the nginx_static_domain and nginx_frontend_domain defined types, but not with the nginx_frontend class because both classes are responsible for the deletion of the default configuration file that is created by the nginx package, which can only happen once.

NOTE:

If the machine to be configured is a REHL, they don't have the /var/www/ or /var/www/html directories by default like Ubuntu machines do. In which case, it will be necessary to add the following lines in the node declaration of the machine in question:

  file { '/var/www':
    ensure => directory,
  }

  file { '/var/www/html':
    ensure => directory,
  }

Single HTTP Server

This is the simplest use case:

class { 'puppet_infrastructure::nginx_static':
  domain   => 'files.example.com',
  www_root => '/var/www/html',
}

This creates an HTTP server and a default server that returns 404 when the website is accessed by the IP.

Alternatively, you can use the defined type to achieve the same result:

puppet_infrastructure::nginx_static_domain { 'files.example.com':
  domain                 => 'files.example.com',
  www_root               => '/var/www/html',
  server_default_create  => true,
}

If you want the website to be accessible by IP you can add

server_default_create => true,
redirect_default      => true,

to the class or defined type declaration. This way, no matter how many servers you add, access by IP will always redirect to the server with redirect_default=> true,.
If we do redirect_default => false,, requests by IP go to server created by the first (alphabetically) configuration inside the directory /etc/nginx/sites-enabled.

Besides the above mentioned deletion of the default nginx configuration, one of the use cases the puppet_infrastructure::nginx_static class was designed to support is single server per machine. Therefore, this class creates the default server by default. On the other hand, the puppet_infrastructure::nginx_static_domain defined type was designed to support multiple server declarations. Therefore the user has to force the default server to be created (and that can only happen in one of the multiple declarations). See examples of these use cases at the last sections of this document.

You have a couple of node declaration examples for a single static HTTP server in the node-examples directory of the puppet_infrastructure module:

Single HTTPS Server without HTTP Redirection

This is the simplest use case, note that since ssl is true, you have to provide a value to static_sslprefix in the class/defined type, usually the same as the domain:

class { 'puppet_infrastructure::nginx_static':
  domain           => 'files.example.com',
  www_root         => '/var/www/html',
  ssl              => true,
  static_sslprefix => 'files.example.com',
  manage_ssl       => true,
}

This creates an HTTPS server and a default server. The default server will answer HTTP and HTTPS requests to the server’s IP and it will (by default) reply 404 (Not Found). NOTE: If you wish to have the website accesible by IP, you could add redirect_default => true but please be aware that this option will activate the HTTP -> HTTPS redirection.

Alternatively you can use the defined type:

puppet_infrastructure::nginx_static_domain { 'files.example.com':
  domain                 => 'files.example.com',
  www_root               => '/var/www/html',
  ssl                    => true,
  static_sslprefix       => 'files.example.com',
  manage_ssl             => true,
  server_default_create  => true,
}

This does not create the default server - see the remarks of the first section of this document.
Note that for either server to manage its ssl, it needs ssl to be true and static_sslprefix to have a value.

You have a couple of node declaration examples for a single static HTTPS server wihtout redirection in the node-examples directory of the puppet_infrastructure module:

Single HTTPS Server with HTTP Redirection

This is the simplest use case, like above, since ssl is true, you have to provide a value to static_sslprefix in the class/defined type. Also note that redirect_to_https can only be true when ssl is true:

class { 'puppet_infrastructure::nginx_static':
  domain            => 'files.example.com',
  www_root          => '/var/www/html',
  ssl               => true,
  static_sslprefix  => 'files.example.com',
  redirect_to_https => true,
  manage_ssl        => true,
}

This creates an HTTPS server, an HTTP server for redirecting and a default server. The default server will answer HTTP and HTTPS requests to the server’s IP and it will (by default) reply 404 (Not Found). The HTTP server redirects to HTTPS.

Alternatively, use the defined type:

puppet_infrastructure::nginx_static_domain { 'files.example.com':
  domain                 => 'files.example.com',
  www_root               => '/var/www/html',
  ssl                    => true,
  static_sslprefix       => 'files.example.com',
  redirect_to_https      => true,
  manage_ssl             => true,
  server_default_create  => true,
}

This does not create the default server - see the remarks of the first section of this document.
Note that for either server to manage its ssl, it needs ssl to be true and static_sslprefix to have a value.

You have a couple of node declaration examples for a single static HTTPS server with redirection in the node-examples directory of the puppet_infrastructure module:

Multiple HTTP and HTTPS Domains on the same Virtual Machine

This is a complete example, including the node declaration, like you would do on your machine:

node 'virtualmachine'{
  # Basic desirable configuration for a generic Ubuntu node
  include puppet_infrastructure::node_base
  # Install nginx and perform configurations common to all servers
  include puppet_infrastructure::nginx_base
  # Open ports for http and https
  firewall { '200 nginx http': proto => 'tcp', dport => 80, action => 'accept', }
  firewall { '210 nginx https': proto => 'tcp', dport => 443, action => 'accept', }

  # This class creates two servers: 
  # - https server that serves the content,
  # - http server that redirects to the https server.
  # It also controls the deploy of ssl certs and key for its domain using static_sslprefix.
  # This class always removes the default config file from the package
  # Note that server_default_create is set to false.
  class { 'puppet_infrastructure::nginx_static':
    domain                  => 'files.example.com',
    www_root                => '/var/www/html/files',
    ssl                     => true,
    static_sslprefix        => 'files.example.com',
    manage_ssl              => true,
    redirect_to_https       => true,
    redirect_to_www         => false,
    server_default_create   => false,
    allow_directory_listing => true,
  }

  # This defined type creates one http server
  puppet_infrastructure::nginx_static_domain { 'basicfiles.example.com':
    domain   => 'basicfiles.example.com',
    www_root => "/var/www/html/${domain}/basicfiles",
  }

  # This defined type creates one http server that allows directory listing
  puppet_infrastructure::nginx_static_domain { 'listedfiles.example.com':
    domain                  => 'listedfiles.example.com',
    www_root                => "/var/www/html/${domain}/listedfiles",
    allow_directory_listing => true,
  }

  # This defined type creates one http server that only allows access by clients with IPs between 192.168.1.1 and 192.168.1.254
  puppet_infrastructure::nginx_static_domain { 'internalfiles.example.com':
    domain       => 'internalfiles.example.com',
    www_root     => "/var/www/html/${domain}/internalfiles",
    ip_whitelist => ['192.168.1.0/24'],
  }

  # This defined type creates one https server that only allows access by clients with IPs between 192.168.1.10 and 192.168.1.50
  # It does not control the deploy of ssl certs and key for its domain because manage_ssl is set to false.
  # In this case it is dependent on existing a multi-domain certificate called "example.com". That is the reason why static_sslprefix is different from the domain.
  puppet_infrastructure::nginx_static_domain { 'specialfiles.example.com':
    domain            => 'specialfiles.example.com',
    www_root          => "/var/www/html/${domain}/specialfiles",
    ssl               => true,
    manage_ssl        => false,
    static_sslprefix  => 'example.com',
    redirect_to_https => false,
    ip_whitelist      => [
      '192.168.1.10/31',
      '192.168.1.12/30',
      '192.168.1.16/28',
      '192.168.1.32/28',
      '192.168.1.48/31',
      '192.168.1.50/32',
    ],
  }

  # This defined type creates:
  # - https_www server, that serves the main content,
  # - http server that redirects to https_www,
  # - https server that redirects to https_www,
  # - the default server that listens to http and https, is accessed by IP and redirects to the https_www server, because redirect_default is set to true.
  # This defined type also controls the deploy of ssl certs and key for its domain because manage_ssl is set to true.
  # The https_www server would be accessed directly, in this example, by:
  # https://www.example.com
  puppet_infrastructure::nginx_static_domain { 'example.com':
    domain                => 'example.com',
    www_root              => "/var/www/html/${domain}/site",
    ssl                   => true,
    manage_ssl            => true,
    static_sslprefix      => 'example.com',
    redirect_to_https     => true,
    redirect_to_www       => true,
    server_default_create => true,
    redirect_default      => true,
  }
}
⚠️ **GitHub.com Fallback** ⚠️