# Starter Guide

{% stepper %}
{% step %}

### Getting Started with PPDRIVE Service

The quickest way to spawn a PPDRIVE service is to simply run:

```sh
ppdrive launch rest
```

This will attempt to start a PPDRIVE **REST** service in [client mode](#client-mode) on port `5000`. If the port is not available, you can try a different port:

```sh
ppdrive launch rest --port [port-number]
```

Once the service is running, you should check out [client mode APIs](/ppdrive/rest-api/client.md) to start uploading and managing files from your application.

However, to have a better understanding of different service types, authentication modes and database setup, we highly recommend you read the rest of this document.
{% endstep %}

{% step %}

### Service and Service Type

A **Service** is a backend process that PPDRIVE runs to expose different APIs for managing the host filesystem. By default, when we launch a service, PPDRIVE spawns a new process on port `5000`. It throws an error if the port is already in use, in which case we can specify a different port with the `--port` option.

To run a PPDRIVE service, we must specify the **Service Type**. The Service Type tells PPDRIVE what protocol we're serving our APIs on. At the time of writing this documentation, PPDRIVE only supports REST (or RESTful APIs) and this is the **default** choice. In future updates, we'll be adding support for gRPC, graphQL, etc.

To run a service with a specific type, open your terminal and run:

```sh
ppdrive launch [service_type]
```

For example, to run a REST service, you would type:

```sh
ppdrive launch rest
```

{% endstep %}

{% step %}

### Auth Mode

In addition to specifying the Service Type, we also need to tell PPDRIVE what **Authentication Mode** (or auth mode) to use. This way, PPDRIVE knows how to protect your filesystem and authenticate incoming requests. What auth mode you choose **greatly depends on why and how you want to use PPDRIVE**. You can specify one or multiple auth modes:

```sh
ppdrive launch [service_type] --auth-modes [auth_mode_1,auth_mode_2, ...]

# Example (single auth mode)
ppdrive launch rest --auth-modes client

# Example (multiple auth modes)
ppdrive launch rest --auth-modes admin,client
```

There are basically 4 auth modes: *client*, *direct*, *admin* and *zero*. Descriptions of each follow.

#### Client Mode

Client mode allows you to connect to PPDRIVE by using a generated **client token**. The token must be provided by external applications in order to perform administrative tasks. The primary goal of this mode is to **connect PPDRIVE to another application you're building separately**. For example, you might be building an invoicing app and want to upload PDF files to PPDRIVE so you can share with customers.

To run PPDRIVE in client mode, run:

```sh
ppdrive launch --auth-modes client
```

Please see [Client API](/ppdrive/rest-api/client.md) to start sending requests to PPDRIVE in client mode.

#### Direct Mode

This mode tells PPDRIVE to allow users to interact *directly* with your filesystem using their login credentials. You don't need a client token. This is the ideal choice if you're building a client application that **allows users to \[manage] files/folders in an authenticated manner** (e.g., a mobile app like Dropbox or Google Drive). You develop the user interface (UI) and interact directly with PPDRIVE API.

#### Admin Mode

Allows you to take full control of PPDRIVE. However, access will only be granted to admin accounts. You'll be able to manage other admins, users, the database and all PPDRIVE components.

#### Zero Mode

No authentication is provided. Be careful not to set this mode accidentally as it will grant unrestricted access to users.
{% endstep %}

{% step %}

### Database

{% hint style="info" %}
All auth modes except *zero* require a database connection.
{% endhint %}

PPDRIVE uses a database to manage its own record of users, filesystem and other activities. At the moment, we support 3 database backends: SQLite (default), Postgres and MySQL. The `--database` option allows you to tell which database url to use:

```sh
ppdrive launch rest --database sqlite://db.sqlite
```

The default value is a SQLite file: `sqlite://db.sqlite`.
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dududaa.gitbook.io/ppdrive/starter-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.