Flocker’s documentation is hosted on S3, fronted by CloudFront.
There are 3 S3 buckets used for documentation.
clusterhq-flocker-docs¶This bucket hosts our public facing documentation.
It has documentation for all marketing releases and weekly development releases.
Documentation is copied to the clusterhq-flocker-docs bucket from the clusterhq-staging-docs bucket during the release process.
The clusterhq-flocker-docs bucket is configured to allow static website hosting, with an index document of index.html and an error document of 404.html.
The clusterhq-flocker-docs bucket has HTTP redirection rules to redirect from moved or obsolete documentation pages.
These redirects are generated by the admin/publish-docs during the release process using configuration in docs/redirects.yaml.
To allow CloudFront to access the bucket, it has the following bucket policy configured:
{
"Version": "2008-10-17",
"Id": "PolicyForPublicAccess",
"Statement": [{
"Sid": "1",
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::clusterhq-flocker-docs/*"
}]
}
It has logging enabled with the following settings:
clusterhq-logs.s3.amazonaws.comflocker-docs.clusterhq.com/s3/There are empty files at /index.html and /en/index.html that redirect to the latest documentation.
gsutil -h x-amz-website-redirect-location:/en/latest/ cp - s3://clusterhq-flocker-docs/index.html </dev/null gsutil -h x-amz-website-redirect-location:/en/latest/ cp - s3://clusterhq-flocker-docs/en/index.html </dev/null
There is an error_pages/404.rst file which is rendered to HTML and uploaded with the rest of the documentation.
The publish-docs tool will update the Error Document property of the target documentation bucket.
The value of the property is the path en/{VERSION}/error_pages/404.html where VERSION is the most recently published version of the documentation.
clusterhq-staging-docs¶This bucket is for staging changes to the main clusterhq-flocker-docs bucket.
It is also used as part of the pre-release testing.
The staging configuration is the same as the production configuration,
with docs.staging.clusterhq.com replacing flocker-docs.clusterhq.com and clusterhq-staging-docs replacing clusterhq-flocker-docs.
clusterhq-dev-docs¶This bucket has documentation uploaded to it from Buildbot as an intermediate stage to being copied to the above buckets.
Buildbot will upload documentation from all builds of release branches or tags here.
The build will be uploaded to a folded named after the python version
(i.e. the output of python setup.py --version).
It is not configured to be publicly accessible.
It has a lifecycle rule that deletes all objects older than 14 days.
We use CloudFront to provide SSL in front of the above S3 buckets. There are 2 CloudFront distributions, one for https://flocker-docs.clusterhq.com/ and one for https://docs.staging.clusterhq.com/. They are pointed at the S3 website URLs (<bucket-name>.s3-website-us-east-1.awazonaws.com).
The configuration of the flocker-docs.clusterhq.com distribution is:
clusterhq-flocker-docs.s3-website-us-east-1.amazonaws.comclusterhq-flocker-docsflocker-docs.clusterhq.comclusterhq-logs.s3.amazonaws.comflocker-docs.clusterhq.com/cloudfront/flocker-docs.clusterhq.comThe rest of the settings can be left at their defaults.
The staging configuration is the same,
with docs.staging.clusterhq.com replacing flocker-docs.clusterhq.com and clusterhq-staging-docs replacing clusterhq-flocker-docs`.
Note
We can’t use an S3 origin, as redirects won’t work.
See the CloudFront documetation for details on uploading SSL key material.