Getting Started

How To Use

There are multiple ways of using Excalith Start Page

Here is how I prefer to use it:

• Docker Version for computers, which runs in a local container.
• Online Version for mobile devices (such as iPad) and remote devices (such as remote VMs). Please refer to Online Version below for some warnings.

After chosing a way to use, you should add the URL of this project to your browsers new tab page. This will override the browsers default new tab page with Excalith Start Page.

Online Version

Online version is more likely a tech preview that will be regularly updated. Using online version as your daily start page may break your configurations one day. I suggest you to use other options instead where you have the control of upates.

With that in mind, you can still use the online version and customize it the way you want. All customiztaions will be stored on your browser storage.

Customizing

Importing Remote Configuration

If you want to use online version, I would recommend you to use the remote configuration import feature. This feature allows you to import your json configuration from an URL using config import <url>. This way, you will always have a backup file of your configuration.

Editing Local Configuration

1. Use config edit command to launch editor
2. When you complete editing, hit SAVE button located on the bottom right of the window
3. If you are seeing Incorrect JSON error, please check your JSON code for errors

Clone

A good approach to make your own start page is to make a clone of this project. I suggest you to use this method over others. This way, you will have control over your configurations and versions. Please note that new versions might have breaking changes. If you want to update to the latest version, please refer to the updating page for more information.

Cloning

1. Clone the project.
2. You may want to remove the .github/workflows folder since it builds Docker image to my Docker repository. (Won't work without my auth information anyway)
3. Install NodeJS and Yarn Package Manager
   • Fire up your beloved terminal
   • Locate to the project directory
   • Use yarn command within project directory to install all dependencies
4. Update the startpage.config.js file and any other files you want to customize

• Use yarn dev command to start local server for preview of your changes

5. Commit and push your changes to your remote repository

Running The App

Local Server

You can use yarn export command to export the project into out folder. Then you can use PM2 or any equivalent service to host the project locally, even auto-start after reboots/restarts.

Docker Image

You can create your own Docker image and host it locally.

Create Docker Image

docker build -t start-page .

Run Docker Image (change the port mapping of 8080 into something you want)

docker run --name start-page --restart=always -p 8080:3000 start-page

Check URL

http://localhost:8080

Deploying To Web

I prefer Vercel for such purposes. You can create a Vercel account, and link your own repository there. Whenever you push your changes into main branch, it will automatically deploy your version into Vercel servers, with a human-readable link.

If you prefer this way, please refer to Vercel Documentation for more information and;

• Do not forget to lock your main branch from anyone. Accept pull requests instead
• Do not push your small changes directly into main branch. I suggest you to use develop branch for this.

Customizing

Config File

Since you have direct control of the config file, you can customize it the way you want!

1. Update the config file as you want.
2. When you are happy with your configuration, commit and push your changes into your remote!

Importing Remote Configuration

Just in case you already have a configuration JSON stored somewhere, you can import it using config import <url>.

Editing Local Configuration

If you want to try out some changes, you can use the built-in editor without hassling with the default config file of yours.

1. Use config edit command to launch editor
2. When you complete editing, hit SAVE button located on the bottom right of the window
3. If you are seeing Incorrect JSON error, please check your JSON code for errors

Docker Container

Docker is another convenient way to host the start page. Using the image, you can choose which version to use and your configuration will not cause any issues with new versions breaking changes. If you want to update to latest version, please refer to the updating page for more information.

You can either use the image from Docker Hub or Github Registry.

From Docker Hub

Pull the latest image

docker pull excalith/start-page:latest

Run the image (change the port mapping of 8080 into something you want)

docker run --name start-page --restart=always -p 8080:3000 -d excalith/start-page

From GHCR

Pull the latest image

docker pull ghcr.io/excalith/excalith-start-page:latest

Run the image (change the port mapping of 8080 into something you want)

docker run --name start-page --restart=always -p 8080:3000 -d ghcr.io/excalith/excalith-start-page

Customizing

Importing Remote Configuration

If you want to use online version, I would recommend you to use the remote configuration import feature. This feature allows you to import your json configuration from an URL using config import <url>. This way, you will always have a backup file of your configuration.

Editing Local Configuration

1. Use config edit command to launch editor
2. When you complete editing, hit SAVE button located on the bottom right of the window
3. If you are seeing Incorrect JSON error, please check your JSON code for errors