Getting Started

How To Use

There are multiple ways of using Excalith Start Page, allowing you to chose the ones suit your needs best.

Here is an example of 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.

Here is the major differences between different uses

Online	Fork	Docker
Always uses latest version, so it can break your local configurations time to time due to new features.	Uses the version you forked until you want to update with upstream. Will not break anything automatically.	Uses the version of the image until you want to update. Will not break anything automatically.
You need to be online to use the page.	This is just the source, you will need to build or deploy in order to use	Docker will host locally using the optimized build just like you would do with a fork
Resources will load slower depending on your connection speed	You will have total freedom: create docker images, deploy to server or serve locally	Since it uses the localhost, it will be faster

After chosing a way to use, you should assign your browsers new tab page with this projects URL (either local or remote). This will override the browsers default new tab page with Excalith Start Page.

Online

BEWARE: 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 with updates. I would suggest you to fork this project and deploy your own version instead. This way, you will have control over updates so nothing will break on a daily usage.

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 on your end. It will be easier to make necessary changes if you need to update it to the new version.

Editing Local Configuration

You can always use the built-in editor for customizing on the fly. This will store your configuration on your browsers local storage. If you are using multiple browsers, you can copy-paste the configuration from the editor into your other browsers.

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 see Incorrect JSON error, please check your JSON for errors

Fork

A good approach to make your own start page is to make a fork 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.

Fork The Project

1. Fork 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
5. Use yarn dev command to start local server for preview of your changes
6. 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 (notice the port 8080)

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 different branches for this.
• Whenever you push your changes on a branch other than main, vercel will provide you a link for preview to test it out. If everything is in order, you can merge it into main to use it as production-ready.

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

You can always use the built-in editor for customizing on the fly. This will store your configuration on your browsers local storage. If you are using multiple browsers, you can copy-paste the configuration from the editor into your other browsers.

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 see Incorrect JSON error, please check your JSON for errors

Docker

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

You can import your remote configuration easily by using config import <url>. This way, you will always have a backup file of your configuration.

Example:

config import https://raw.githubusercontent.com/excalith/.dotfiles/main/config/startpage/excalith-start-page.json

Editing Local Configuration

You can always use the built-in editor for customizing on the fly. This will store your configuration on your browsers local storage. If you are using multiple browsers, you can copy-paste the configuration from the editor into your other browsers. Even better, you can create a public repository for this config file so you can import it anytime.

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 see Incorrect JSON error, please check your JSON for errors