Documentation for the deconst project: a continuous delivery pipeline for heterogenous documentation. It's also used to develop deconst itself, like some kind of documentation ouroboros. You can read the documentation itself at deconst.horse.
To build this documentation standalone, use the Deconst
client. Use the Sphinx preparer and a clone
of https://github.com/deconst/deconst-docs-control
as the control repository.
DNS entries for deconst.horse
, build.deconst.horse
, staging.deconst.horse
,
and content.staging.deconst.horse
are managed by Cloud DNS entries in the
"drgsites" account. They should be pointed to the appropriate load balancers.
TLS certificates are currently retrieved from Let's Encrypt by a manual, downtime-inducing process. To reissue them:
** WARNING: Script reissuance is currently broken. Use at your own risk. **
-
Run
script/reissue
in your deconst/deploy clone to reissue and download the new certificates tole_certificates/
. -
Copy and paste the new certificate as the
ssl_key:
entry incredentials.yml
. -
Use
script/encrypt
to encrypt the modified credentials file and commit and push it to nexus-credentials. -
Invoke Ansible to roll it out:
$ script/deploy \
-e 'credentials_update=true' \
-e 'service_pod_restart=true' \
-e 'staging_restart=true' \
-e 'strider_restart=true'
These instructions will prepare and submit the content and assets for this deconst documentation in a dev env in Kubernetes with Minikube.
-
If necessary, deploy the presenter service
-
Open a new shell
-
Prepare the content
wget https://raw.githubusercontent.com/deconst/preparer-sphinx/master/deconst-preparer-sphinx.sh chmod u+x deconst-preparer-sphinx.sh ./deconst-preparer-sphinx.sh ls _build/deconst-envelopes/ ls _build/deconst-assets/
-
Submit the content
The
CONTENT_SERVICE_APIKEY
must match theADMIN_APIKEY
set when deploying the content service.export CONTENT_SERVICE_URL=$(minikube service --url --namespace deconst content) export CONTENT_SERVICE_APIKEY=$ADMIN_APIKEY wget https://raw.githubusercontent.com/deconst/submitter/master/deconst-submitter.sh chmod u+x deconst-submitter.sh ./deconst-submitter.sh
-
Prepare the staging content
The staging environment is a specially configured content service and presenter pair that allow users to preview content. Normally the Strider server will push preview content to the staging environment but this is how you would manually do it.
export CONTENT_ID_BASE=https://github.com/staging/deconst/deconst-docs/ export ENVELOPE_DIR="_build/deconst-staging-envelopes" export ASSET_DIR="_build/deconst-staging-assets" ./deconst-preparer-sphinx.sh ls _build/deconst-staging-envelopes/ ls _build/deconst-staging-assets/
-
Submit the staging content
export CONTENT_SERVICE_URL=$(minikube service --url --namespace deconst staging-content) export ENVELOPE_DIR="$(pwd)/_build/deconst-staging-envelopes" export ASSET_DIR="$(pwd)/_build/deconst-staging-assets" ./deconst-submitter.sh
-
Confirm the content envelopes are in mongo
kubectl run --namespace deconst --rm -it mongo-cli --image=mongo:2.6 --restart=Never -- mongo mongo.deconst.svc.cluster.local show dbs use content db.envelopes.count() db.staging_envelopes.count()
-
Deploy the deconst control repo
-
Recreate the content DB
The content is stored in the mongo DB files at
/data/deconst/mongo
in the minikube VM. Delete the DB files and the mongo pod. Kubernetes will automatically restart the mongo pod.minikube ssh sudo rm -rf /data/deconst/mongo/* exit MONGO_POD_NAME=$(kubectl get pods --selector name=mongo --output=jsonpath={.items..metadata.name} --namespace deconst) kubectl delete po/$MONGO_POD_NAME --namespace deconst
Now you can run through the instructions above again to prepare and submit the content.