On-premise setup: Linux CLI

Prerequisites

Linux server (Ubuntu/Debian recommended), amd64
Docker Engine + Compose v2 installed and running
sudo / root access
Server IP or domain name
Internet (online setup) or the Docker image TAR files (offline setup): download amd64.zip and extract it
SSL certificate + key in one folder (HTTPS only). Files must be named server.crt and server.key
16 GB RAM preferred for first install, 8 GB minimum
40 GB+ free disk (images + media + mongo)

Check Docker:

docker --version
docker compose version
docker info

Docker and Docker Compose version output

If Docker is not installed:

Install: https://docs.docker.com/engine/install/ubuntu/
Post-install: https://docs.docker.com/engine/install/linux-postinstall/

Install the CLI

5.0.3 below is the current version as of this writing. Check the latest release notes or ask your Pickcel contact for the current one.

Download the .deb

wget https://console.pickcel.com/players/onprem-cli/pickcel-cli_5.0.3_amd64.deb

No internet on the server? Download pickcel-cli_5.0.3_amd64.deb on another machine and copy it to the server.

Install

sudo apt install ./pickcel-cli_5.0.3_amd64.deb

Verify

pickcel-cli --version

Setup wizard

sudo pickcel-cli setup

Workspace directory

Default: /srv/pickcel/pickcel-server. Press Enter to accept, or enter a parent folder (the CLI appends pickcel-server automatically).

Server IP

Auto-detected NIC list, or enter manually
Example: 192.168.1.100
Skip any Docker bridge interface shown (e.g. 172.18.0.1). Pick your real LAN NIC

Protocol

HTTP. Default public port 80
HTTPS. Default public port 443 (needs server.crt + server.key)

Public port (GLOBAL_PORT), optional

Press Enter for standard port (80 for HTTP, 443 for HTTPS)
Or enter a free port if 80/443 is already taken (e.g. 8443 for HTTPS)
Access the site as https://<ip>:8443 when using a custom port

Domain (HTTPS only)

Optional. Press Enter to use IP only.

SSL (HTTPS only)

Choose whether to provide certificates now
If yes, enter the directory containing server.crt and server.key
Certs are copied to nginx/ssl/ in the workspace
Skip during setup and add later with pickcel-cli config

Setup wizard: SSL certificate directory prompt

Install dashboard server?

No. Pickcel CMS only (console + admin + backend + webserver)
Yes → choose:
- Only dashboard server. Dashboard only, no Pickcel CMS images
- Dashboard with Pickcel. Full CMS plus local dashboard on port 3030
Dashboard Server URL (when not installing a local dashboard): optional remote URL, press Enter to skip

Setup wizard: dashboard server URL prompt

Office app (not asked for dashboard-only mode)

Default No. Set Yes only for LibreOffice document conversion (adds libreoffice container + TAR in offline mode).

MongoDB backup (not asked for dashboard-only mode)

Default No. Set Yes for a daily Mongo backup sidecar (mongo-backup container).

Firewall rules (Linux + root)

Default Yes, opens inbound TCP for your public port (and 3030 when Pickcel + dashboard). Skip with --no-firewall or answer No.

Setup mode

Online
Offline

Pulls images from Docker Hub.

Setup wizard: online/offline mode selection

Loads from TAR files (prompted for TAR folder; path is saved for future runs).Get the TAR files: download amd64.zip and extract it. It contains the six required TARs below. The Office app and dashboard TARs are not included.One .tar per service. Version in the filename can differ, matching uses a keyword in the name.Pickcel only / Pickcel + Dashboard (required):

Service	Example filename	Also matches if name contains
Webserver	`pickcel-webserver-5.0.0.tar`	`webserver`, `nginx`
Backend	`pickcel-backend-5.0.1.tar`	`backend`
MongoDB	`pickcel-mongodb-5.0.0.tar`	`mongo`
Console	`pickcel-console-5.0.1.tar`	`console`
Admin	`pickcel-admin-portal-5.0.0.tar`	`admin`
Redis	`pickcel-redis-7.tar`	`redis`, `memcache`

Optional:

When	Example filename
Office app = Yes	`pickcel-libreoffice-converter-1.0.0.tar`
Dashboard installed	`pickcel-signage-dashboard-server-1.0.tar` (or name contains `dashboard`)

.tar.gz / .tgz also work.

Never mix amd64 and arm64 TARs on the same host.

When the wizard asks for the TAR folder, enter the full path of the folder with the TAR files. See How to get the TAR folder path below.

How to get the TAR folder path

Leave the setup wizard open and waiting. Get the path from a second terminal:

Open a new terminal window on the server (or a second SSH session).
Go into the folder with the TAR files. For example:
cd ~/pickcel-tars
Print the folder’s full path:
pwd
It shows something like /home/your-name/pickcel-tars.
Select that path and press Ctrl + Shift + C to copy it.
Go back to the setup wizard window, press Ctrl + Shift + V to paste it, then press Enter.

First run can take several minutes.

Setup wizard: containers started successfully

Verify setup

pickcel-cli status

You should see containers such as webserver, backend, console-frontend, admin-frontend, mongo, memcache with status running. Open the CMS in a browser:

HTTP: http://<your-ip> or http://<your-ip>:<port> if using a custom port
HTTPS: https://<your-domain-or-ip>

First login needs a valid on-premise license (not auto-migrated from older installs). With no license yet, the console’s Welcome screen generates a Request Key. Send it to your Pickcel contact, then apply the License Key they return.

Common setups

HTTP (typical LAN)

sudo pickcel-cli setup
# Pick IP → HTTP → Enter for default port
# No dashboard, No Office, Online
# Allow firewall if prompted

HTTPS with domain

sudo pickcel-cli setup --domain example.com --ssl-dir /path/to/certs

Or run interactively: HTTPS → domain → SSL directory with server.crt / server.key.

Offline (no internet)

Download amd64.zip and extract it. It contains:

pickcel-webserver-5.0.0.tar
pickcel-backend-5.0.1.tar
pickcel-mongodb-5.0.0.tar
pickcel-console-5.0.1.tar
pickcel-admin-portal-5.0.0.tar
pickcel-redis-7.tar

Run:

sudo pickcel-cli setup --offline --images-dir /path/to/tars

Port 80 already in use (HTTPS on 443 only)

Choose HTTPS
Press Enter for default port 443 (only 443 is published, port 80 does not need to be free)
Or set a custom public port (e.g. 8443) if 443 is also taken
Access the site as https://<ip>:8443

Non-interactive helpers

sudo pickcel-cli setup --online
sudo pickcel-cli setup --offline --images-dir /path/to/tars
sudo pickcel-cli setup --domain example.com --ssl-dir /path/to/certs
sudo pickcel-cli setup --no-firewall --no-start
sudo pickcel-cli --workspace /custom/path setup

Global -w / --workspace must appear before the command.

IP, protocol, port, dashboard, Office app, and Mongo backup are always asked interactively. No flag skips them.

After setup: day-to-day commands

Managing the stack (start / stop / status)

# Uses local images if available; prompts if any are missing
sudo pickcel-cli start

sudo pickcel-cli start --online

sudo pickcel-cli start --offline --images-dir /path/to/tars

sudo pickcel-cli stop
pickcel-cli status

When running pickcel-cli start without flags: all images exist locally → offline-safe mode (--pull=never); any image missing → prompts online vs offline (interactive), or requires explicit flags (non-interactive).

Logs and info

pickcel-cli logs                  # all containers
pickcel-cli logs backend -f       # follow one container
pickcel-cli logs webserver -t 100 # last 100 lines
pickcel-cli info                  # workspace, mode, versions, URLs

Change configuration

sudo pickcel-cli config

Change IP, protocol, public port, domain, SSL, dashboard URL, Office app, Mongo backup. Services restart automatically unless you pass --no-restart.

pickcel-cli config --domain example.com --ssl-dir /path/to/certs
pickcel-cli config --no-restart

Don’t run config right after hand-editing NEXT_PUBLIC_* values in .env. It regenerates .env and can overwrite them. Use rebuild instead.

Update Docker images

sudo pickcel-cli update --online
sudo pickcel-cli update --online -y          # skip confirm
sudo pickcel-cli update --offline --images-dir /path/to/tars
sudo pickcel-cli update --online --refresh-static   # re-copy apps/players from backend image

For an offline update, download the latest amd64.zip, extract it, and point --images-dir at that folder.

Change NEXT_PUBLIC_* values (Google Maps, MS Teams, etc.)

Console and admin frontends bake NEXT_PUBLIC_* keys into the Docker image at build time. Editing .env alone is not enough, you must rebuild. Edit workspace .env (e.g. /srv/pickcel/pickcel-server/.env):

NEXT_PUBLIC_GOOGLE_MAPS_API_KEY (console)
NEXT_PUBLIC_MSAL_TEAMS_CLIENT_ID, NEXT_PUBLIC_MSAL_POWERBI_CLIENT_ID (console)
NEXT_PUBLIC_ADMIN_AUTH_DECRYPTION_KEY, NEXT_PUBLIC_ADMIN_FIREBASE_WEB_CONFIG (admin)

sudo pickcel-cli rebuild

Then hard-refresh the browser (Ctrl+Shift+R). Options: --console, --admin, --no-restart, --pull. Not available in dashboard-only install mode (no console/admin images).

Workspace folder

Default location: /srv/pickcel/pickcel-server CLI config is stored separately at /etc/pickcel-cli/config.json (system) or ~/.config/pickcel-cli/config.json (user).

Path	Purpose
`.env`	Server URL, protocol, secrets
`docker-compose.yml`	Services and image tags
`nginx/`	Web server + SSL certs (`nginx/ssl/server.crt`, `server.key`)
`mongo-data/`	Database files
`mongo-backups/`	Daily dumps (when Mongo backup enabled)
`media/`	Uploaded media
`dist/public/`	Apps, players, widgets (synced from backend image)
`image-versions.json`	Pinned image tags
`.pickcel-cli/install-mode.json`	Install mode

Apps and player installers are not inside the .deb package. They are copied from the pickcel/backend image during setup and updates.

Troubleshooting (quick)

Docker not running

sudo systemctl start docker
docker info

Permission denied

Use sudo for setup/start/stop/update. Optionally add user to docker group:

sudo usermod -aG docker $USER
# log out and back in

Port in use

sudo ss -tulpn | grep -E ':(80|443|3030|8080|27017|6379)'

Stop the conflicting service or use a custom public port during setup/config.

Cannot open in browser

Check pickcel-cli status, firewall allows your ports, try curl http://127.0.0.1 on the server itself.

Apps / players 404

Backend image must be loaded. Run:

sudo pickcel-cli update --online --refresh-static

BrightSign wrong IP

Happens after IP change. Run pickcel-cli config to update IP and restart, or run an update so autorun.zip is re-patched from .env (needs unzip/zip on host).

Offline missing images

Check TAR filenames contain the service keyword (backend, console, etc). Use --images-dir with the correct path.

Google Maps / Teams not working after .env edit

Run pickcel-cli rebuild, then hard-refresh the browser.

HTTPS certificate error

Cert and key must be a matching pair, named server.crt / server.key, valid for your domain.

SSL skipped at setup

HTTPS will not work until you run pickcel-cli config with --ssl-dir.

Images not pulling

Check ping hub.docker.com and docker pull pickcel/webserver:5.0.0. Use offline mode if no internet.

Ports (default)

Service	Port
HTTP	80
HTTPS	443
Dashboard (local, Pickcel + dashboard mode)	3030
Backend (internal)	8080
MongoDB	27017
Redis (memcache container)	6379

Firewall: setup can add rules automatically when run with sudo. Otherwise open inbound TCP for the ports you use.

Notes

Stack uses v5 images: pickcel/backend, pickcel/mongodb, pickcel/webserver, pickcel/console, pickcel/admin-portal
Old names (backendv5, mongov5, console-next, and v4 names like pickcel-nginxv4) are no longer used
Dashboard-with-Pickcel always uses host port 3030 for the local dashboard (separate from GLOBAL_PORT)
Player packages come from the backend image sync, not a separate cloud download in the CLI

Update pickcel-cli

If you want to update the pickcel-cli tool itself, run:

sudo pickcel-cli update-cli

Troubleshooting only: check which build environment and update source are baked into your package.

pickcel-cli update-src

If you want to update the Docker images instead, see Update Docker images above.

Other internal docs

WSL2 setup (Windows 10/11)

Running this CLI on Windows? Get Docker working in WSL2 first.

Windows Server setup

Windows Server: WSL2 + Docker Engine, plus firewall and port forwarding.

Windows GUI setup

Set up on-premise using the Windows GUI application.

On-premise installation (Ubuntu)

Manual Ubuntu install, setup script, and license activation.

Dashboard app setup

Configure the dashboard rendering server.

​Install the CLI

​Setup wizard

​Verify setup

​Common setups

​Non-interactive helpers

​After setup: day-to-day commands

​Managing the stack (start / stop / status)

​Logs and info

​Change configuration

​Update Docker images

​Change NEXT_PUBLIC_* values (Google Maps, MS Teams, etc.)

​Workspace folder

​Troubleshooting (quick)

​Ports (default)

​Notes

​Update pickcel-cli

​Other internal docs