Docker

Docker

You can use prebuilt images using Docker Compose

Prerequisites

• Docker
• A device with amd64 or arm64 based architecture

Installation

Preperation

To install, create a file called docker-compose.yml and paste the code below into it.

Compose - Volume (Recommended)

This option is simple to use and the recommended way. This compose file will be used to

1. Pull the image from Docker registry
2. Run the image as a container on port 8080 (You can change the port as you wish.)
3. Create a volume called excalith-start-page where your configurations will persist

version: '3.8'

services:
  start-page:
    container_name: start-page
    image: excalith/start-page
    restart: unless-stopped
    ports:
      - 8080:3000
    volumes:
      - data:/app/data

volumes:
  data:
    name: excalith-start-page

Compose - Bind Mount (Advanced)

This option is more advanced than the previous one, which will mount your directory as the data folder for Excalith Start Page. In order for you and Docker to have permissions to read and write, you should adjust those permissions yourself, depending on your OS and settings.

Here is the warning from Docker Documentation regarding bind volumes:

Warning:

Bind mounts allow write access to files on the host by default.

One side effect of using bind mounts is that you can change the host filesystem via processes running in a container, including creating, modifying, or deleting important system files or directories. This is a powerful ability which can have security implications, including impacting non-Docker processes on the host system.

And documentations regarding file sharing

• Linux
• Mac
• Windows

With this in mind;

• Update user
  • Either use 0:0 to give root permissions
  • Use your own UID:GID respectively
• Update your directory by replacing username with your own username and a custom folder for your data to persist.
• Optionally, update your port from 8080 into one you wish

When you launch the app for the first time, it will either read the existing settings.json file or create a new file for it.

Note: While using bind mounts, you will only have the required settings.json file within your directory. This is intended by following best practices to keep things tidy and respect your space. For more information regarding this, and some utility scripts to download your select assets and themes from your terminal check this discussion thread.

version: '3.8'

services:
  start-page:
    container_name: excalith-start-page
    image: excalith/start-page
    restart: unless-stopped
    user: 0:0
    ports:
      - 8080:3000
    volumes:
      - /home/username/excalith-start-page/:/app/data"

volumes:
  data:
    name: excalith-start-page

If you are still having troubles with this option (ie. no settings.json were created or log errors from Docker), you may need to change RWX permissions at your own risk.

Running Compose

You should be in the same directory where you created the docker-compose.yml file. From there, you should run the following command on your terminal:

docker-compose up -d # Detached mode starts in background

This will

• Pull the latest image from Docker Hub depending on your hardware
• Create a container called excalith-start-page
• Provide you an access using the port on compose file (default 8080)
• Create a volume for your configuration to persist

Launching

Launch the URL on your browser. Please notice the port 8080 and update it if necessary.

http://localhost:8080

Updating

Navigate to the directory where your docker-compose.yml located.

# Stop start page container
docker compose down

# Pull latest image of start page
docker compose pull

# Start container with the latest image
docker compose up -d

Optionally, you can remove unused images

Caution

This will remove all unused images that are currently not running

docker image prune

Uninstalling

Navigate to the directory where your docker-compose.yml located.

# Stop the service
docker compose down

# Remove compose file
rm docker-compose.yml

Optionally, you can remove unused images

Caution

This will remove all unused images that are currently not running

docker image prune