Quick start guide

This guide describes how to download, install, and run all the components necessary to get started with application development using Carbon LDP as quickly as possible.

Overview

This guide will cover the following steps, which are commonly required to setup a
new development environment and to get started building a new application quickly.

  1. Install Docker
  2. Configure and run the Carbon platform
  3. Run the Carbon workbench
  4. Create an agent
  5. Create a new application
  6. Develop with the JavaScript SDK, REST API, and optional tools
  7. Provide feedback to help improve Carbon LDP
  8. Update your instances when new versions are released

This guide will also cover subsequent steps, after the initial setup, such as starting and stopping instances, troubleshooting, and updating software when new versions are available.

You may want to review the complementary Quick Start video on YouTube.

LICENSE Information

Please review the Carbon LDP Software License Agreement before accessing or using the software.
Downloading, installing, copying, or otherwise using the software constitutes your agreement to the terms of the license.

Install Docker

The Carbon Platform and Workbench are packaged in Docker containers, which ensure the software will always run the same, regardless of its environment (Mac, Windows, or Linux). Docker allows you to spin up a Carbon platform (server) and a workbench (GUI), with just a single command for each.

To get started, you will first need to install the Docker on your computer. Download the binaries and get basic installation instructions for Docker here:

https://www.docker.com/products/overview#/install_the_platform

After installing Docker, execute the following command to validate that it was correctly installed and is running in your machine.

docker run hello-world

If all went well, you should see a message similar to the following in your terminal.

Hello from Docker!
This message shows that your installation appears to be working correctly.

Configure and run the Carbon platform

Carbon LDP runs as a server that listens for, and responds to RESTful HTTP requests for managing resources. This is the essential platform, which provides an authentication server, a database and security management. It’s where all the data for your application is stored and managed. Now that you have Docker up and running, you can configure and run the platform with the following steps:

Register for updates and community support

You should register in our community mailing list before running an instance of the platform. Registration allows us to notify you with important information such as when new features or bug fixes are released. It is also a suggested prerequisite for getting better community support through GitHub issue tracking; we prioritize our registered users first. What’s more, registration qualifies you to receive Valued Feedback Rewards for providing useful feedback. If you haven’t already registered, please Join our Mailing List. After filling out a very brief form, you’ll be returned to this guide.

Create the platform’s directory structure

In a folder on your machine, create a directory named carbon, and inside of it create a directory called config and another called data. Like this:

  • carbon/
    • config/
    • data/

Create the platform configuration file

The platform’s configuration is initialized from the properties contained in a file called config.properties, which you will need to create in the carbon/config directory.

config.properties

platform.domain = localhost:8083
platform.protocol = http

# These credentials will be used to create the system agent, similar to the root user of linux
# Please note them down somewhere safe as they will be removed from the configuration file as soon as you run your instance
platform.system-agent.username = system-agent@example.com
platform.system-agent.password = system

# The name of your instance
authentication.realm-name = Your Carbon LDP Instance

token.key = generateARandomStringAndPlaceItHere

It is important to make note of the platform.system-agent.username and platform.system-agent.password because, for security, those properties will be automatically removed from the file when the platform is started for the first time.

For the authentication.realm-name, you can put any unique name for your server instance. “Local Dev”, for example.

For the token.key, you can put any random alpha-numeric string. You can use this one that we have just generated for you:

Run a platform instance

Run the following command to start your own platform instance for the first time. The command will fetch the image from a Docker repository and will install and run the Carbon Platform.

Note: You must replace /your/directory/path/carbon/data with the absolute path to the data directory you just created, and /your/directory/path/carbon/config with the absolute path to the config directory. Leave the portions after the colons near each path in tact (:/opt/carbon/data and :/opt/carbon/config)

docker run -d --name carbonldp-platform -p 8083:8083 \
    -v /your/directory/path/carbon/data:/opt/carbon/data \
    -v /your/directory/path/carbon/config:/opt/carbon/config \
    carbonldp/carbonldp-platform


After executing the command, open localhost:8083/platform/api/. If the server is running successfully you should see a response in XML similar to the following:

Notes:

  • What you’ll see actually see in the browser may depend on the configuration you created and the browser you are using.
  • It may take a while for carbon to start. Keep refreshing the page. If after 5 minutes, the XML response still doesn’t display, something went wrong.
  • If you can’t load the page, check the URL. It MUST end with a slash /. All URLs handled by the platform will follow this rule.

Congratulations! You have a Carbon platform instance up and running!

Useful Docker commands

If you have problems running the instance, the following Docker commands may help you troubleshoot your situation.

  • docker ps --all – Will give you a list of all the containers you have and their status
  • docker stop carbonldp-platform – Will stop the carbonldp-platform container
  • docker start carbonldp-platform – Will start the carbonldp-platform container
  • docker rm carbonldp-platform – Will remove the carbonldp-platform container (so you can recreate it for example)
  • docker logs carbonldp-platform – Will output the logs of the carbonldp-platform container
  • docker logs -f carbonldp-platform – Will output the logs of the carbonldp-platform container and will continue to do so until stopped

Run the Carbon workbench

The Carbon workbench is a web app that helps you interact with the Carbon platform through a graphical user interface (GUI). Among the features it provides are

  • Document Explorer – a GUI for visualizing and editing Carbon documents
  • SPARQL Client – a GUI for entering and execute SPARQL queries and SPARQL updates with results displayed in a friendly format
  • App Creator – a GUI for creating and editing Carbon Applications

Using the Carbon Workbench will aid your development process, especially in the beginning, because it allows you quick, visual verification of the data you create
using either the JavaScript SDK or REST API. It also provides an easy way to query and inspect or modify data with SPARQL.

To run the Carbon workbench, execute the following command (replacing the configured host, port, and protocol where appropriate).

docker run -d --name carbonldp-workbench -p 8000:80 \
    -e "CARBON_HOST=localhost:8083" \
    -e "CARBON_PROTOCOL=http" \
    carbonldp/carbonldp-workbench

After executing the command, open localhost:8000 in your web browser. If the workbench is running, you should be presented with a login page like this:

Note: It may take a while for the workbench to start. Keep refreshing the page. If, after 5 minutes, the page still doesn't load, something went wrong.

Create an agent

At this point, you can login to the Workbench using the platform.system-agent credentials you used when creating the config.properties file. Generally, however, you will want to reserve that Agent for special administrative operations only. The Platform System Agent isn't restricted by security. It can do anything inside of your instance - even destroy it. That's why it is not recommended to use it for normal actions (think of it like the root user on a Linux machine, which you shouldn't use for day-to-day work). Following are the steps required to create a new Agent that you can use for day-to-day work:

  • Navigate to http://localhost:8000/login in your web browser.
  • Click the hyperlink where it says, "Don't have an account? Create one".
  • Enter name, e-mail address, password, and profile ID and then click "Register".

You should now be able to login with the e-mail address and password you used to register your new agent.

Create a new application

"Applications" are the data spaces where Carbon helps you manage the data for a given solution. Multiple applications can exist on a single platform instance. If you are planning to store data for a blog, for example, you can create an application for it (e.g. "My Blog"). Now you'll create a discussion forum? Great, another application it is (e.g. "My Discussion Forum"). And so on.

Applications separate not only your data, but your security scheme and configuration too.

To create your first application, login to the workbench. The dashboard will appear empty (it's a placeholder for some future features). Click on "Apps" in the left-hand sidebar menu as shown below.

Next, click the "Create app" button as shown below...

Fill out the resulting form with basic information about your app. This information is used to display your app in the applications list. The slug will be used in a unique identifier for your app and will appear in a root position of all Carbon URLs used with your app. Following is an example:

Once you've successfully created your first app, you can click on Apps in the left-hand sidebar menu to see it in the applications list as shown below. Clicking on the name of the application in the applications list, will navigate into the application space where you can then use the Document Explorer, the SPARQL Client, and other features of the Workbench.

Develop with the JavaScript SDK, REST API, and optional tools

Of course, the app you created is not a functioning app; it's just the data space in Carbon for the application you now need to build. The next step is to use the JavaScript SDK with your client-side code to build a client application. Head over to Getting Started with the JavaScript SDK to learn how.

Note: If you are running your own local instance of the platform, you'll likely need to turn off https in the SDK. To do that configure the following setting when creating your platform context (you'll understand what this means after reading the JavaScript SDK Getting Started guide):

 carbon.setSetting( "http.ssl", false );

You should also bookmark the Carbon LDP JavaScript SDK API Reference on GitHub, which lists all the API objects and methods you can use.

REST API, and optional tools

Following are some additional resources that you might find helpful during your development.

  • Documentation - The Carbon LDP product documentation for developers.
  • Getting Started with the REST API - You can do anything with the REST API that you can do with the JavaScript SDK. However, the REST API is for lower-level programming that is generally more tedious than using the JavaScript SDK. Most developers prefer to work primarily with the JavaScript SDK.

Provide feedback to help improve the product

Carbon LDP is in constant development. As such, we urge you to provide feedback as you evaluate the product so that we can improve it. Both positive and negative feedback are welcome; we love it all. In fact, we even give Valued Feedback Rewards to registered users who provide feedback (feature requests, identified defects, etc).

Please provide feedback by opening issues in Carbon LDP's general wiki and issue tracking project, carbonldp on GitHub.

To learn more about how we use GitHub to track project issues and feedback submitted by the user community, see: GitHub Conventions and Workflow for Carbon LDP.

Update your instances when new versions are released

Whenever we release a new version of the platform or the workbench, you should update your instances so you benefit from the new features and bug fixes. To be notified when new versions are available, please be sure to register for our community mailing list. If you haven't already registered, please Join our Mailing List.

To update the platform and workbench you need to pull the remote images again by running the following commands:

docker pull carbonldp/carbonldp-platform:latest
docker pull carbonldp/carbonldp-workbench:latest

After that, stop your running instances and delete them with the following commands:

docker stop carbonldp-platform && docker rm carbonldp-platform
 docker stop carbonldp-workbench && docker rm carbonldp-workbench
 

You should then create a data backup just in case something goes wrong with the new version. To do that, copy and rename the carbon folder containing your config and data.

You can then spin your instances again with the same commands you used before:

docker run -d --name carbonldp-platform -p 8083:8083 \
    -v /your/directory/path/carbon/data:/opt/carbon/data \
    -v /your/directory/path/carbon/config:/opt/carbon/config \
    carbonldp/carbonldp-platform
docker run -d --name carbonldp-workbench -p 8000:80 \
    -e "CARBON_HOST=localhost:8083" \
    -e "CARBON_PROTOCOL=http" \
    carbonldp/carbonldp-workbench:latest