> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pickcel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pickcel: On-Premise Setup

> Initial setup guide for Pickcel on-premise installation

> [!WARNING]
>
> **This guide describes the older v4 manual installation method** (`git clone
>     signage-on-premise-v4` plus a Node setup script). Pickcel's on-premise platform has since
> moved to a v5 architecture (Next.js console/admin) with dedicated installers — for a new
> installation, use [Linux CLI setup](/on-premise/linux-cli-setup) or [Windows GUI
> setup](/on-premise/windows-gui-setup) instead. The License Activation flow below (Request Key
> → License Key → Apply) matches what a live v5 install shows at first login, so it likely still
> applies conceptually, but the exact wording and Admin Portal steps haven't been re-verified
> against v5.

> [!NOTE]
>
> **Prerequisites**
>
> * **Operating System:** Ubuntu 20.04
> * **Internet Connection:** Required during installation. Post-installation, the software can run offline.

### 1. Install Utilities

Install `curl`, `git` & `ifconfig` (for knowing the IP address of your network in case you don't know it already).

```bash theme={null}
sudo apt-get install curl git net-tools
```

### 2. Verify Pre-installed Software

Make sure that Node.js & Docker are installed.

```bash theme={null}
node --version
```

```bash theme={null}
docker --version
```

If they are installed, these commands would list the versions without any errors.

### 3. Install Node.js

If Node.js is not installed, follow these steps:

1. Install node version manager (nvm):
   ```bash theme={null}
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
   ```

2. Verify if `nvm` is properly installed or not using:
   ```bash theme={null}
   nvm --version
   ```

3. Then install Node.js (version 18) using:
   ```bash theme={null}
   nvm install 18
   ```

4. To pick up the `nvm` command:
   ```bash theme={null}
   source ~/.bashrc
   ```

### 4. Install Docker

To install Docker, go to their [installation page](https://docs.docker.com/engine/install/ubuntu/), choose your operating system from the list & follow the instructions.

> [!WARNING]
>
> If you installed Docker in the previous step, then you will have to wait for a minute or so before proceeding further for Docker socket to be running.

To verify if Docker socket is running, execute the following command. If the socket is running, it won't throw any error.

```bash theme={null}
sudo docker images
```

### 5. Network Configuration

To know your network's IP address, you can run the `ifconfig` command & note down the required IP address. It will be required in a later step.

### 6. Clone Repository

Now clone the `signage-on-premise-v4` repository.

```bash theme={null}
git clone --branch main https://github.com/pickcel-LQ/signage-on-premise-v4.git
```

It will ask for GitHub credentials. Enter them & hit `Enter`.

Once the repository is cloned, using `cd` command, navigate & go inside the `signage-on-premise-v4` folder.

> [!NOTE]
>
> By this point, Node & Docker should be installed & IP address should be noted down. These are the prerequisites for the next step.

### 7. Run the Setup Command

1. Go inside the setup folder.
   ```bash theme={null}
   cd ./setup
   ```

2. Install the dependencies.
   ```bash theme={null}
   npm install
   ```

3. Run the setup command.
   ```bash theme={null}
   npm run docker-setup
   ```

The script will ask for IP address first. Type the IP address that you noted down & hit `Enter`.

> [!NOTE]
>
> Building the images for the first time would take quite a while (about **15-20 minutes**).

Once everything is completed successfully, you'll see a **done!** message in the terminal at the end.

> [!NOTE]
>
> **Note:** The installation of dependencies is done now. The following steps should now run without internet as well.

Now open the browser, enter the IP address (the one that you noted down) & you should see the signage page.

***

## License Activation

License activation requires a **two-way key exchange** between the customer's on-premise installation and the Pickcel Admin Portal.

> [!NOTE]
>
> **Process Overview:**
>
> 1. Customer generates a **Request Key** from their browser
> 2. Admin uses this to generate a **License Key** in the Admin Portal
> 3. Customer applies the **License Key** to activate their installation

### Part 1: Generate Request Key (On Customer's System)

Open the customer's on-premise installation in a browser using the IP address configured during setup.

1. Enter the customer's organization details:
   * Organization Name
   * Admin Name
   * Email & Contact Details
2. Click **Proceed**
3. A **Request Key** will be generated
4. **Copy this Request Key**: you'll need it in the next step

***

### Part 2: Generate License Key (On Admin Portal)

> [!WARNING]
>
> This step must be done on **your system** (the admin), not the customer's.

1. Log in to the **Pickcel Admin Portal**
2. Navigate to **Onsite** section from the sidebar
3. Click **+ Add Onsite Partner** button (top left)
4. In the modal that appears:
   * **Paste the Request Key** (from Part 1)
   * Select **Number of Screens**
   * Set **Expiry Date**
5. Click **Apply**
6. A **License Key** will be generated
7. **Copy this License Key**: you'll apply it on the customer's system

***

### Part 3: Apply License Key (Back to Customer's System)

Return to the customer's browser where the on-premise installation is open.

1. You should see a prompt asking for the license key
   * If not, click **Apply** or refresh the page
2. **Paste the License Key** (from Part 2)
3. Click **Apply**

> [!TIP]
>
> **Success!** You should now see the dashboard with:
>
> * Customer's email
> * Number of screens assigned
> * Expiry date
>
> Click **Proceed to Login** to access the CMS.

***

## Updating an Existing License

When a customer needs to extend their license or increase screen count, you'll need to generate a new license key.

### Step 1: Generate Updated License Key (Admin Portal)

1. Log in to the **Pickcel Admin Portal**
2. Navigate to **Onsite** section from the sidebar
3. Search for the customer using their **Name or Email**
4. Click on the customer entry
5. Click the **Edit button** (pencil icon)
6. Update the details in the modal:
   * **Number of Screens** (if increasing capacity)
   * **Expiry Date** (for license extension)
   * Other details as needed
7. Click **Update**
8. **Copy the New License Key** that's generated

***

### Step 2: Apply Updated License (Customer's System)

1. On the customer's on-premise CMS, click the **Profile Icon** (top right)
2. Select **Update License**
3. A modal will appear with a text area
4. **Paste the New License Key**
5. Click **Apply**

> [!TIP]
>
> The system will immediately update and display the new expiry date and screen capacity.

***

## Other internal docs

> **[Windows GUI setup](/on-premise/windows-gui-setup)**
>
> Set up on-premise using the Windows GUI application.

> **[Linux CLI setup](/on-premise/linux-cli-setup)**
>
> Set up on-premise using the CLI tool on Linux.

> **[Dashboard app setup](/on-premise/dashboard-app-setup)**
>
> Configure the dashboard rendering server.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.