Quick start guide

This guide describes how to setup a new development environment and how to get started with building a new application.

Overview

This guide will cover the following steps:

  1. Installing Docker
  2. Running the Carbon LDP™ platform
  3. Running the Carbon LDP™ workbench
  4. Developing against Carbon LDP™
  5. Keeping up-to-date
  6. Providing feedback

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

LICENSE Information

Please review the 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.

Installing Docker

The Carbon LDP™ 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 the Workbench (administrative GUI), with just a single command for each.

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

https://www.docker.com/get-started

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.

Running the Carbon LDP™ platform

Carbon runs as a server that listens for, and responds to RESTful HTTP requests for managing resources. It’s where all the data of your application will be stored and managed.

Now that you have Docker up and running, you can run the platform by following the steps below:

1. Create the platform’s home directory

In a folder on your machine, create a directory for the platform to store its data, e.g.: carbonldp/

Note that by default the platform is configured to be exposed through localhost:8083. This means that all the ids the platform will create are going to have that as a base.

To change that or other configuration parameters please see Platform configuration.

2. 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 run the instance.

Notes:

  • Replace /your/directory/path/carbonldp with the absolute path to the directory you just created. Leave the portions after the colon near the path intact (:/opt/carbonldp/shared)
  • Complete the contact information (last three lines)
docker run -d --name carbonldp-platform -p 8083:8083 \
    -v /your/directory/path/carbonldp:/opt/carbonldp/shared \
    carbonldp/carbonldp-platform:5 \
        --carbonldp.contact.first-name="" \
        --carbonldp.contact.last-name="" \
        --carbonldp.contact.email="" \
        --carbonldp.contact.company=""

Contact information

The command shown above will run the “standard” edition of the platform. To use it, users are required to provide contact information. The primary reason we record this information is so that we can understand how many people use the platform (unique users). We may also use the information to notify you with important news or announcements about the product, but you can rest assured that we will never share your information with anyone.

For information on how to run other versions of the platform, such as the Enterprise edition, please see: Platform configuration.

Please review the License Agreement for any other question related to this topic.

 

If you want to learn what each of these parameters indicate, you can read the following section:

Command explanation
docker run \                                                    # The 'run' command creates a container and starts it based on a docker image
    \                                                           # === Docker's run parameters
    -d \                                                        # Detached (meaning don't attach the instance's output to this command line)
    --name carbonldp-platform \                                 # The name of the docker container
    -p 8083:8083 \                                              # Expose port 8083
    -v /your/directory/path/carbonldp:/opt/carbonldp/shared \   # Map the local directory '/your/directory/path/carbonldp' to the container's '/opt/carbonldp/shared'
    carbonldp/carbonldp-platform:5 \                            # The docker image to use to create the container
        \                                                       # === Carbon LDP's configuration properties
        \                                                       # == Contact information
        --carbonldp.contact.first-name="" \                     # Your first name
        --carbonldp.contact.last-name=""                        # Your last name
        --carbonldp.contact.email="" \                          # Your email
        --carbonldp.contact.company=""                          # The name of your company

After executing the command, open localhost:8083/.system/platform/. If everything went well you should see a response in XML similar to the following:

Carbon LDP™ platform's API response example

Notes:

  • What you’ll actually see in the browser may depend on the configuration you created and the browser you are using.
  • It may take a while for the platform 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

Running the Carbon LDP™ workbench

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

  • Document Explorer – a GUI for visualizing and editing Carbon LDP documents
  • SPARQL Client – a GUI for entering and executing SPARQL queries and SPARQL updates with results displayed in a friendly format

Using the Carbon LDP™ Workbench will aid your development process, especially in the beginning, because it allows you to visually explore the data you save with the JavaScript SDK or REST API. It also provides an easy way to query, inspect and modify data with a SPARQL Client.

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

docker run -d --name carbonldp-workbench -p 8000:80 \
        -e "CARBONLDP_HOST=localhost:8083" \
        -e "CARBONLDP_PROTOCOL=http" \
        carbonldp/carbonldp-workbench:5

If you want to learn what each of this parameters are indicating you can read the following section:

Command explanation
docker run \                                                    # The 'run' command creates a container and starts it based on a docker image
    -d \                                                        # Detached (meaning don't attach the instance's output to this command line)
    --name carbonldp-workbench \                                # The name of the docker container
    -p 8000:80 \                                                # Map container's port 80 to local port 8000
    -e "CARBONLDP_HOST=localhost:8083" \                        # Set env variable 'CARBONLDP_HOST' to 'localhost:8083'
    -e "CARBONLDP_PROTOCOL=http" \                              # Set env variable 'CARBONLDP_PROTOCOL' to 'http'
    carbonldp/carbonldp-workbench:5                             # The docker image to use to create the container

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

In this page you’ll be able to view the specifics of your platform, such as its version, the number of documents stored on it and the number of triples the platform has stored so far.

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.

Developing against Carbon LDP™

Of course, the platform instance you just created is just the space in which Carbon LDP™ will store the data 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.

REST API

Everything that the platform does is exposed through its REST API. This API is an implementation of the W3C LDP recommendation. Head over to the Getting Started with the REST API

JavaScript/TypeScript

To ease development against the REST API in a JavaScript/TypeScript environment we have created an SDK compatible with all the major web browsers and Node.js. Head over to Getting Started with the JavaScript SDK to learn how to use it.

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

Keeping up-to-date

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 join our mailing list.

To update the platform and workbench you need to follow the steps below:

  1. 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
  2. Pull the remote newest images again by running the following commands:
    docker pull carbonldp/carbonldp-platform:5
    docker pull carbonldp/carbonldp-workbench:5
  3. You should then create a data backup just in case something goes wrong with the new version.
    To do that, copy and rename the carbonldp folder containing your config and data.
  4. 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/carbonldp:/opt/carbonldp/shared \
        carbonldp/carbonldp-platform:5 \
            --carbonldp.contact.first-name="" \
            --carbonldp.contact.last-name="" \
            --carbonldp.contact.email="" \
            --carbonldp.contact.company=""
    docker run -d --name carbonldp-workbench -p 8000:80 \
        -e "CARBONLDP_HOST=localhost:8083" \
        -e "CARBONLDP_PROTOCOL=http" \
        carbonldp/carbonldp-workbench:5

Providing feedback

Carbon LDP™ is a product 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.