Console Upload Tutorial

---

These instructions will guide you through your first console-based file upload to Ohloh.

These instructions are written with Linux and OS X users in mind. It should be compatible with most *nix environments. The Ohloh console upload service also works with Windows, but you will require an scp or sftp implementation.

This guide focuses on details that are unique to Ohloh's service, and does not attempt to explain some standard tools. These instructions assume that you are comfortable using the command line, are familiar with the use of SSH keys, and have access to the scp or sftp tool.

Project Managers Only

In order to use the console upload service, you must be registered as a project manager on Ohloh.

From your project's main Ohloh page, find the "Who Manages This Project?" box on the right side of the page, and click the "I'm a Manager" link.

If you are the first manager on Ohloh for this project, you will immediately become this project's manager. If this project already has other managers, your request will be need to be approved by an existing manager. They will be notified via email about your request.

Provide Your Public SSH Key

The Ohloh upload server uses SSH key pairs for authentication. See the Upload FAQ for more information about SSH keys. We require RSA-encrypted SSH keys (DSA won't work).

Once you have located your public SSH key, enter it on your account profile edit page.

Confirm Your Upload Account

After you upload your SSH public key, an account will be created for you on our upload server. This may take 5-10 minutes.

You will be able to sftp to the upload server once your account is ready:

sftp me@upload.ohloh.net

If your SSH key requires it, you will be prompted for your password at this point. If it doesn't work or your SSH key does not require a password, this means that either your account is not yet ready, or your SSH key pair is not properly configured. Give it a few minutes and try again, or ask for help in our forums.

Prepare Your Project Files

Make very sure that your project files have their correct filenames. The filenames you use during upload become permanent and must be unique.

Ohloh considers uploaded files to be immutable -- once uploaded, they cannot be re-uploaded, even if you delete them from Ohloh. You must choose a new filename for each upload.

If you make a mistake and upload the wrong bits for a filename, you cannot re-upload them. You must delete the incorrect bits, and upload the corrected bits under a new filename.

Create Your Instruct XML File

The instruct XML document gives Ohloh information about your packages and releases. Uploaded project files will be ignored until they are referenced by an instruct XML document. Although we refer to this document as an "instruct" file, you may name it anything you like, as long as it ends in ".xml". A handy convention is to refer to what files you're uploading (e.g. "debug_kit.xml").

At a minimum, an instruct file must contain at least one package and one release.

There should be one <file> element for each project file you have uploaded. You must specify a name attribute that matches the project file name. Do not specify any paths; use the base filename.

Here's an example instruct file:

<packages>
  <package name="Source Code">
    <releases>
      <release name="1.0.0">
        <files>
          <file name="myfile-1.0.0.tgz"/>
        </files>
      </release>
    </releases>
  </package>
</packages>

You can download instruct.xsd to help validate your document. This is an example of using xmllint to verify your instruct XML file:

xmllint --schema instruct.xsd myinstruct.xml

Upload Your Project Files

Your home directory on the upload server contains a subdirectory for each project you manage. Within this project directory, there are subdirectories for files, instructs, and logs.

Your project files should be placed in the files subdirectory.

scp myfile-1.0.0.tgz me@upload.ohloh.net:myproject/files

Upload Your Instruct XML File

Your instruct file should be placed in the instructs subdirectory.

scp myinstruct.xml me@upload.ohloh.net:myproject/instructs

Confirm The Upload

Files uploaded to the upload server should appear on your Ohloh project page within a few minutes. If not, there may be a problem.

Upload Status

The basic status of your upload can be determined by observing the state of your instruct XML file. You can do this via sftp:

sftp me@upload.ohloh.net
cd myproject/instructs
ls

If your instruct XML file is still present, then your upload has not yet been processed. If the file is not processed after 5-10 minutes, there may be a system error and you should contact Ohloh support.

If your instruct XML file has been renamed to have a .fail extension, then there has been an error during processing, probably an XML validation error or a missing or misspelled file.

If your instruct XML file has been renamed to have a .done extension, then it has been successfully processed and all files were accepted. Your files should be visible on your Ohloh project page. If not, contact Ohloh support.

Viewing the Error Log

If an error has occurred during upload processing, the details can be found in an error log:

scp me@upload.ohloh.net:myproject/logs/upload.log .

The error messages may be helpful in diagnosing a problem with your instruct XML, but may also reflect internal Ohloh technical problems. If you have any questions or concerns, please contact Ohloh support.

Further Help

If you have additional questions, please post in our forums or contact us directly via email using the links at left.

We welcome all feedback on these instructions and our upload service. Thank you!