Creating Your Key

First, check for an existing key by opening up a terminal or Git Bash and entering:

$ cat ~/.ssh/id_rsa.pub

• If you get output, it should be a long string that starts with "ssh-" and ends with your email address. This is your public key. Copy the whole string, and skip to the next section.

  Caution

  You'll be asked for your passphrase for this key in a following step; if you don't remember it, proceed with creating a new one.

• If you get "No such file or directory" (or see a string with no email address), you can generate a new key by following these steps:
  1. In Terminal/Git Bash, type: ssh-keygen -t rsa -C "your_email@example.com". Make sure to fill in the email address that you use with Atlas.
  2. At the prompt to "Enter file in which to save the key (/Users/you/.ssh/id_rsa)", just press Return.
  3. Enter a passphrase. You'll need to do this twice.

You should see output indicating that your key has been created. At this point you can run this command again:

$ cat ~/.ssh/id_rsa.pub

Now you should see a string that starts with "ssh-" and ends with your email address. Copy that string.

Adding Your Key to Atlas

In Atlas, click your username in the top right corner to get to the Account Settings page. Then click the SSH tab.

Under "Add an SSH Key," add some descriptive title (e.g., "local machine"), and then paste the string you copied previously under "Public Key."

Click the "Add Key" button, and that's it! You should now have the ability to clone down Atlas repos and work with files locally.

Download Git

You can download Git from the git-scm site. Just follow the instructions for your platform.

Clone Your Project from Atlas

1. Go to the Project Settings page and copy the git@git.atlas.oreilly.com... URL from the box on the right.

   

2. From the command line, the git clone <your_URL> command will pull down your project's repository. By default, using this command will pull the repo into a directory named by your project name. You can override this by putting a new directory name at the end of the command.

3. You'll be prompted for your SSH key passphrase; enter the passphrase you chose when you created your SSH key.

Now you can open and edit your files in your favorite text editor. You can also use Git's command-line tools to perform version control operations not available in the Atlas web app.

Pushing Edited Files Back to Atlas

Once you've made your edits, you'll need to add any new files to be tracked by Git, commit your changes, and then push back to Atlas:

1. Add any new files so that Git can start tracking them. Use git add <filename> to add an individual file. Use git add . to add all files in the current directory and all subdirectories.
2. Commit the changes using git commit -am "commit message". Try to use the commit message to leave yourself a note about what you were doing. For example, if you were just adding a big section on the foo method, you'd add a message like "Added section covering foo."
3. Push the changes back up to Atlas using git push origin main.

Getting a Diff

You can use Git to get a diff between the files in your local checkout and the files on Atlas. To do this, use git fetch:

$ git fetch origin
Password:
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 3 (delta 2), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
From https://atlas-admin.oreilly.com/git/1230000000065
   92d4f99..e9fbbe2  main     -> origin/main

Once you've fetched, you can use this command to see the files that have changed between your local copy and the remote copy:

$ git diff --name-only main..origin/main

This command will just give you the list of files. If you want to see the actual differences, just leave off the --name-only flag. Once you're satisfied that nothing nefarious is in there, you can merge in the changes you just fetched using this command:

$ git merge origin/main

Input Parameters

project

Full name of the Atlas repo to build (e.g., runemadsen/Hello-World).

formats

Comma-separated list of formats to build. Possible options are pdf, epub, html, and atlas

branch

Name of the branch to build. This is useful for building older versions, or managing multiple concurrent versions of a project.

A successful response does not mean that the build finished. You will need to manually check the build_url to know when each of the formats in the build succeeded. There are 4 different states that a build format can return.

Response: Queued

A queued response means that the build is waiting in the queue to be performed.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "queued"
    }
  ]
}

Response: Working

A working response means that the build is currently being performed.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "working"
    }
  ]
}

Response: Completed

A completed response means that the build successfully completed. You can then grab the file from the download_url. If the build succeeded with warning, you can read those warnings in the message property.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "completed",
      "download_url" : "http//www.something.com/something.pdf",
      "message" : "a potential warning"
    }
  ]
}

Response: Failed

A failed response means that the build failed. Details about the error message are in the message property of the response.

{
  "build_url" : "https://atlas.oreilly.com/api/builds/1",
  "status" : [
    {
      "format" : "pdf",
      "status" : "failed",
      "message" : "This is an error message"
    }
  ]
}

Atlas API Ruby Gem

Gem to interact with the O'Reilly Atlas API. Requires Ruby >=1.9.

Install this gem by running:

$ gem install atlas-api

You can build a specific project by calling the atlas build command line:

$ atlas build ATLAS_TOKEN PROJECT FORMATS BRANCH

A real world example of this would look something like this:

$ atlas build abcdefg oreillymedia/atlas_book_skeleton pdf,epub,html main