Welcome to the repository for Algorithmia's Developer Center. Here you will find guides, tutorials, sample apps, as well as some documentation on getting started with the API and basic set up.
These docs are built on Jekyll. Learn more over at the official Jekyll page.
You're going to need:
- Linux or OS X — Windows may work, but is unsupported.
- Ruby, version 2.3.0 or newer - Avoid
sudo gem installat all costs - see rvm.io. - Bundler — If Ruby is already installed, but the
bundlecommand doesn't work, just rungem install bundlerin a terminal. - Homebrew - If you're using a Mac, install homebrew to help with the installation of imagemagick.
sudo apt install ruby ruby-dev zlib1g-devsudo apt-get install imagemagick
Install imagemagick:
brew install imagemagick
Install via:
bundle install --path vendor/bundle
If installation for nokogiri fails due to libxml2 support, install it via:
gem install --install-dir vendor/bundle/ruby/<ruby_version_numbwe> nokogiri -v "<failing_nokogiri_version_number>" -- --with-xml2-include=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX<os_version_number>.sdk/usr/include/libxml2 --use-system-libraries
If installation of therubyracer gem fails due to recent changes in Catalina, do the following:
gem install libv8 -v '3.16.14.19' -- --with-system-v8
rvm autolibs disable
brew unlink v8
brew link [email protected] --force
gem install therubyracer -v 'version'
brew unlink [email protected]
brew link v8
rvm autolibs enabled
More info here if issues persist.
- Fork this repository on Github.
- Clone your forked repository with
git clone https://github.com/YOURUSERNAME/dev-center.git cd dev-center- Make sure you have rvm and node installed.
- To set up submodules and install dependencies, run
npm run setup.
- Do bear in mind that you will need to able to communicate with GitHub via SSH for this to function as expected.
- If you are having trouble with some of the gems, try running
bundle update, then runbundle installagain. Ifbundleis not available,gem install bundler.
- To start both the Node and Jekyll test servers with auto-regeneration, run
npm run devcenter:devandnpm run server:devin two separate terminal windows. - If you don't need auto-regeneration, you can run
npm run startto build static dev-center files and only start the Node server.
You can now see the developer center at http://localhost:4000/developers/. The API docs are located at http://localhost:4000/developers/api/.
To run only the Jekyll server at http://localhost:4001/developers/, first follow steps 1-5 above, then
To Run Public Marketplace Version:
npm run devcenter:public
To Run Enterprise Version:
npm run devcenter:enterprise
Note: Search functionality is intentionally disabled for local development, as rebuilding the search index on each file change is terribly slow. If you need to use the same plugins in development as are used in production, update _config-dev.yml so that the production plugins folder is used:
plugins_dir: _plugins-prod
The Algorithmia API Docs and Synapse UX Toolkit are included as submodules in this project. If you make updates to either of these repositories that you would like reflected in the Dev Center, cd into the submodule directory and check out the commit with your updates. Then cd back to the dev-center directory, run git add [submodule directory], and commit.
If updates are made to the api-docs, you will need to run npm run apidocs:build in order to see the changes.
There are three different options you can use for running end to end tests: local, tunnel, and cloud:
• Local: WebDriver runs tests using locally installed browsers against a local Node server.
• Tunnel: WebDriver uses a BrowserStack integration to run the tests inside browsers within virtual machines. The requests are proxied to a local Node server.
• Cloud: Same as tunnel, except the tests are run against our test environment instead of a local server.
To run end to end tests:
- Reach out to the UX team to get BrowserStack credentials.
- Ensure the following environment variables are set when calling the below scripts:
BROWSERSTACK_USERNAME,BROWSERSTACK_ACCESS_KEY
- Run one of the following:
npm run e2e:localnpm run e2e:tunnelnpm run e2e:cloud
All posts, layouts, includes, stylesheets, assets, and whatever else is grouped nicely under the root folder.
Find all pages under the _pages directory, organized by URL route structure.
The compiled Jekyll site outputs to _site/. Do not edit anything in this directory (or your changes will be lost).
The first thing that goes in each new post is the YAML front-matter. Below is an example of front-matter:
---
layout: article
title: "Example post!"
excerpt: "This is an example post."
date: 2016-01-05 11:39:38
categories: guides example
tags: [stuff, things]
# optional fields:
exclude_from_search: true #false by default
share: false #true by default
sitemap: false #true by default
---For our purposes, the minimum you will need is layout, title, date, & categories. The other fields only need to be present if you are overriding the default.
Use excerpt to set the text that appears in under the article title in the collection view of all articles. The template will automatically grab the first sentence if you do not set an excerpt, so you'll want to make sure that is appropriate or set one by hand. Note: If the first line of your post is a templating tag, it will not automatically pick up an excerpt.
In the case of author, the default author can be found in _config.yml. The default author is Algorithmia. If you need to add yourself as an author, please fill out your author data in _data/authors.yml. Then, set the author field in your front-matter in the post.
When you're mentioning the number of algorithms in the marketplace, or the maximum number of algorithms you can call, to be consistent across the whole developer center, please use variables instead.
For example, if you want to mention the number of algorithms we have in an article, use the following:
And if you need a pre-trained model or utility function for your project, check out the over {{site.data.stats.marketplace.total_num_algorithms}} algorithms and microservices that have been deployed on Algorithmia's <a href="https://algorithmia.com/algorithms">AI Marketplace</a>.
You can find more variables in the _data/stats.yml file.
Image and video assets can be prefixed with {{site.cdnurl}} to automatically serve them via CDN. Note that it can take over 24h for the CDN's cache to clear, so if replacing an asset which is already in the CDN, consider renaming the asset to force its immediate reloading.
This Jekyll site uses several plugins to help generate content and make the site extra-awesome. All plugins live in the plugins directory. In order to speed up development, we've opted to use some plugins only in a production environment. You can see which plugins are used for development versus production by opening the _plugins-dev or _plugins-prod folders, which use symlinks to refer to files in the plugins folder. Included in the plugins directory:
Emoji.rb: Emojify your posts. Simply use the text version (like you would on GitHub) and this plugin will replace it with the emoji image. See the emoji cheat sheet for a full listing of emoji codes. 💅author_page_generator.rb: This plugin will generate a page that lists all posts by a given author.jekyll-lunr-search.rb: (Production Only) Generates the index of all posts for the search function.navmenu.rb: A tag plugin to generate the side navigation menu.strip.rb: Removes some excess whitespace and new lines generated by the Liquid templating process.
Default: false
Description: If set to true, enforces a content security policy for the application.
Default: false
Description: If set to true, disables the Strict-Transport-Security header on server responses.
Default: false
Description: If set to true, disables the X-Content-Type-Options header on server responses.
Default: false
Description: If set to true, disables the X-Frame-Options header on server responses.
Default: false
Description: If set to true, disables the X-XSS-Protection header on server responses.
Default: undefined
Description: The authorization bearer token necessary for the application to expose Prometheus metrics at the /metrics endpoint.
First, fork the repository and follow the instructions above to get set up. Make sure all your changes work locally. When you are ready, make a pull request to this repo and we will review the changes. Be sure to describe the changes, attach screenshots of any cosmetic changes, and if applicable, link to the open issue.
When contributing please refer to the Algorithmia manual of style for grammar, punctuation, voice, and tone.
If you find a bug, can't follow the documentation, or have a question -- please submit an issue!
We will respond to you or reach out for more information as soon as possible. And, of course, feel free to submit pull requests with bug fixes or changes.