Yes, you read that right! We finally managed to complete the migration and update of the DevCenter, something we had in works for quite some time now.
The new DevCenter is completely open source, you can find its source code on GitHub, and every page of the DevCenter includes links to edit that page directly on GitHub (and to easily send a Pull Request with your fixes / suggestions), as well quick links to create GitHub issues with an automatic reference to the page.
Why did it take so long? We have more than a 100 articles on our DevCenter, and we wanted to go through all, update links and texts to get it up to date as much as possible. The transition also involved removing a couple of now irrelevant articles, and adding completely new ones.
For example, the Bitrise CLI and bitrise.yml section was rewritten from the ground up. When we wrote the original section for our previous DevCenter we were still kind of new to the CLI, as the current open source Bitrise CLI just replaced our previous, closed source solution. A lot has changed since, the CLI evolved rapidly, especially since we switched to monthly releases, and we now automate the development, testing and distribution of the bitrise.io website, our blog and now the new DevCenter, in addition to lots of mobile apps and sample projects using the Bitrise CLI.
With the updated DevCenter we tried our best to guide you through the vast Bitrise ecosystem, including both the bitrise.io web service and our open source build runner / CLI, and we're determined to keep it that way. So, if you'd have a question or issue related to a page of the DevCenter, feel free to click the create an issue on the DevCenter's GitHub page, link which you can find at the bottom of every page on the DevCenter, to let us know where the docs should be improved.
How we deploy the DevCenter to GitHub Pages
Finally, a couple of technical details about the DevCenter.
The full source code can be found on GitHub, and can be built into a completely static website using the wonderful MkDocs tool.
The repository includes the bitrise.yml we use for testing, building and distributing the DevCenter, so you can just bitrise run setup to install the required tools on a Mac/Linux, start the local webserver with bitrise run up, run the tests with bitrise run ci, and distribute it with bitrise run deploy-to-github-pages.
The current "compiled" static site can also be found on the gh-pages branch of the GitHub repository.
We use a wide variety of tools for our services, for example our Blog (which is also open source) uses middleman, also compiled to a static site which is hosted on Amazon S3. You can find a related guide, well, on our DevCenter ;)
For the DevCenter we wanted to try another tool, so we went with MkDocs for organizing and building the code, and GitHub Pages for hosting the static site. This was our first project to utilize GitHub Pages, and we were pleasantly surprised. Deploying the repository to GitHub Pages is quite straightforward, once you understand the two types of sources it supports:
- You can use GitHub Pages' built in Jekyll feature.
- Or you can build your static HTML, css, js, .. resources, and store that on the gh-pages branch directly.
As we decided to use MkDocs and we wanted to keep our options open (if we'd decide to host the devcenter somewhere else in the future) we went with the second option. Generating all the static resources with MkDocs is as simple as running mkdocs build --clean, which by default will generate the files into a site/ subdirectory. All we had to automate is to run mkdocs build --clean, and sync the site/ directory to the gh-pages branch using simple git commands. (You can see the exact commands we run in the devcenter's bitrise.yml in the deploy-to-github-pages workflow)
That's all, once you push your generated resource files to the gh-pages branch GitHub will pick it up automatically and make it available under a *.github.io/ URL. During the migration of the DevCenter we did use this URL (bitrise-io.github.io/devcenter in case of our DevCenter) and we had absolutely no issue with it.
Once we decided it's time to replace devcenter.bitrise.io, to point to this GitHub pages domain instead of the old devcenter's servers we had to configure a couple of additional things. The official documentation did not include every detail, although it was quite good to get started.
We ended up adding a CNAME entry on our DNS service (dnsimple) pointing to our GitHub organization's GitHub pages URL (bitrise-io.github.io). (Note, we started with an ALIAS entry but we got a warning on GitHub after the first deploy, suggesting to use a CNAME instead, so we replaced the ALIAS with a CNAME entry)
As the devcenter is a repository of the bitrise-io organization on GitHub, simply opening bitrise-io.github.io will not work, its GitHub pages URL is bitrise-io.github.io/devcenter. So, what's missing? You have to define this "custom domain" (devcenter.bitrise.io in our case) on GitHub too. We did that, setting devcenter.bitrise.io as the Custom domain in the Settings of the repository on GitHub, and everything worked in less than a minute!
We were thrilled, as we could figure out these details in less than an hour, and everything seemed to work properly! But then we went ahead and published a change and a new release of the DevCenter with some minor modifications, went to check it on devcenter.bitrise.io and... The site was gone O_O
To be precise, when we visited devcenter.bitrise.io the 404 page of bitrise-io.github.io was presented. We were surprised and thought we messed something up. Double checked the configurations, and we found that our Custom domain configuration disappeared from the GitHub repository settings. First we thought that was something we did accidentally, so we did set it again, and the site came back - hurray!! Then we went ahead and deployed another change and the site was gone again..
This is most likely a bug on GitHub right now, and it might only affect sites which don't utilize Jekyll and instead publish the compiled files directly to the gh-pages branch, but the behavior was consistent; after every deploy the Custom domain entry disappeared from GitHub repository settings.
The solution was quite simple, although we had to go through quite a couple of GitHub documentation pages until we realized that there's another option to set the Custom domain for GitHub pages. The old school way (which was the only way before the Custom domain option was added to the GitHub UI) is to add a CNAME file to the root directory of the gh-pages branch, with nothing but the custom domain URL as the content of the file. In our case this was a simple one liner, added to the deployment script: echo "devcenter.bitrise.io" > CNAME, right before committing and pushing to the gh-pages branch.
We now deployed quite a few updates to the DevCenter, with nothing but merging the Pull Request including the change
- everything else is handled by bitrise.io and GitHub pages automatically! No issues, it just "magically" works! If you're interested, you can find the full configuration we use in the bitrise.yml file, in the DevCenter's GitHub repository!
