SSL

This page documents Generation 1, which has reached End of Life. Gen 1 apps use docker-compose.yml. For current documentation, see SSL.

You can easily secure traffic to your application using TLS (SSL).

Add a Secure Port to Your Manifest

Edit your app's docker-compose.yml file to create a port mapping for your secure traffic. For most web applications this will be port 443, the standard for HTTPS.

You'll also need to set the protocol for the port using the convox.port.<port>.protocol label. Use https as the value if you want to get HTTP headers and don't need to support websockets. Otherwise use tls. For example:

web:
  labels:
    - convox.port.443.protocol=https
  ports:
    - 80:3000
    - 443:3000

When you're done editing, redeploy your application.

$ convox deploy

Your app is now configured to serve encrypted traffic with a self-signed certificate on port 443. To use a real certificate, you will need to acquire an SSL Certificate and apply it to your SSL endpoint. See the following sections for more information.

Acquire an SSL Certificate

Generate a Certificate

You can request an SSL certificate for any domain you control using convox certs generate:

$ convox certs generate foo.example.org
Generating certificate... OK, acm-c28a4f6e0b37
ZONE         NAME                                                TYPE   VALUE                                                              CHECK
example.org  _6123456789abcdef0123456789abcdef.foo.example.org.  CNAME  _99dcba9876543210fedcba9876543210.ghijklmnop.acm-validations.aws.  missing
Deploy the domain once convox certs shows acm-c28a4f6e0b37 as dns

Add the DNS records the command prints at your DNS provider and leave them in place. AWS Certificate Manager (ACM) issues the certificate once the records answer, and convox certs then shows it as dns. Apply it with convox ssl update only after that, because convox ssl update accepts only an issued certificate. Each run requests a new certificate. See Certificate DNS Validation for the steps for each DNS provider.

DNS validation requires rack version 20261021234916 or newer, and CLI version 3.25.12 or newer, or 20261021234916 or newer. With an older CLI, or against an older Rack, the certificate uses email validation. On a rack version older than 20261021234916, convox certs does not list the certificate until ACM issues it, so keep the id the command prints.

Wildcard certificates

You can generate a wildcard certificate with *, e.g. convox certs generate "*.example.com". However, note that the wildcard only covers that level of the domain and not the bare domain. For instance, *.example.com will cover www.example.com, mail.example.com and so on, but not example.com itself.

Purchase a Certificate

You can also purchase an SSL certificate from most registrars and DNS providers. Convox is a fan of Gandi.

Import your certificate and private key using convox certs import:

$ convox certs import example.org.pub example.org.key
Importing certificate... OK, acm-5d0c7e2b91f4

Apply the Certificate

You can then apply a certificate to your load balancer with convox ssl update:

$ convox ssl update web:443 acm-5d0c7e2b91f4
Updating certificate... OK

Note: A Gen 1 load balancer is a Classic Load Balancer by default, and it takes only RSA 1024-bit and 2048-bit certificates from ACM. On a Classic Load Balancer, convox ssl update refuses an ACM certificate with any other key type and leaves the App unchanged. See ssl update.

Inspect SSL Configuration

You can use the Convox CLI to view SSL configuration for an app.

$ convox ssl
ENDPOINT  CERTIFICATE       DOMAIN       EXPIRES
web:443   acm-5d0c7e2b91f4  example.org  2 months from now

Managing Certificates

The Convox CLI includes commands that let you list, update, and remove SSL certificates.

Listing Certificates

You can see the IAM server certificates in your AWS account and the ACM certificates in the Rack's region with convox certs:

$ convox certs
ID                                DOMAIN                 EXPIRES            STATUS
acm-5d0c7e2b91f4                  example.org            2 months from now  imported
acm-c28a4f6e0b37                  foo.example.org        1 year from now    dns
cert-production-1758802512-04821  *.*.elb.amazonaws.com  5 days ago         imported

Certificates imported with convox certs import or generated with convox certs generate have ids like acm-c28a4f6e0b37. The self-signed certificate the Rack uploads for https and tls ports is an IAM server certificate named cert-<rack>-<unix time>-<number>, and other IAM server certificates are listed by name.

Updating Your SSL Certificate

When it's time to update your SSL certificate, import your new certificate and use convox ssl update again:

$ convox certs import example.org.pub example.org.key
Importing certificate... OK, acm-9b1e60d2c8f7

$ convox ssl update web:443 acm-9b1e60d2c8f7
Updating certificate... OK

Removing Old Certificates

You can remove old certificates that you are no longer using. Pass the full id.

$ convox certs delete acm-5d0c7e2b91f4
Deleting certificate acm-5d0c7e2b91f4... OK

See Also

• SSL (Gen 2)
• Custom Domains
• Load Balancers