2021-06-07 14:40:51 +03:00
# Flame
2021-11-14 00:47:59 +03:00
![Homescreen screenshot ](.github/home.png )
2021-06-08 13:51:50 +03:00
2021-06-07 14:40:51 +03:00
## Description
2021-08-03 11:22:55 +03:00
2021-11-10 18:45:30 +03:00
Flame is self-hosted startpage for your server. Its design is inspired (heavily) by [SUI ](https://github.com/jeroenpardon/sui ). Flame is very easy to setup and use. With built-in editors, it allows you to setup your very own application hub in no time - no file editing necessary.
2021-06-07 14:40:51 +03:00
2021-11-14 00:47:59 +03:00
## Functionality
2021-11-14 01:28:43 +03:00
- 📝 Create, update, delete your applications and bookmarks directly from the app using built-in GUI editors
2021-11-15 13:40:33 +03:00
- 📌 Pin your favourite items to the homescreen for quick and easy access
2021-11-14 01:28:43 +03:00
- 🔍 Integrated search bar with local filtering, 11 web search providers and ability to add your own
- 🔑 Authentication system to protect your settings, apps and bookmarks
2021-11-18 15:05:32 +03:00
- 🔨 Dozens of options to customize Flame interface to your needs, including support for custom CSS and 15 built-in color themes
2021-11-14 01:28:43 +03:00
- ☀️ Weather widget with current temperature, cloud coverage and animated weather status
- 🐳 Docker integration to automatically pick and add apps based on their labels
2021-06-07 14:40:51 +03:00
2021-08-03 11:22:55 +03:00
## Installation
2021-06-21 14:59:17 +03:00
### With Docker (recommended)
2021-06-28 02:33:27 +03:00
2021-11-05 18:39:42 +03:00
[Docker Hub link ](https://hub.docker.com/r/pawelmalak/flame )
```sh
2021-11-14 00:47:59 +03:00
docker pull pawelmalak/flame
2021-11-05 18:39:42 +03:00
# for ARM architecture (e.g. RaspberryPi)
docker pull pawelmalak/flame:multiarch
2021-11-14 00:47:59 +03:00
# installing specific version
docker pull pawelmalak/flame:2.0.0
```
2021-06-28 02:33:27 +03:00
2021-11-15 01:20:37 +03:00
#### Deployment
```sh
# run container
docker run -p 5005:5005 -v /path/to/data:/app/data -e PASSWORD=flame_password flame
```
2021-06-21 14:59:17 +03:00
#### Building images
2021-08-03 11:22:55 +03:00
2021-06-07 14:40:51 +03:00
```sh
2021-06-18 15:12:17 +03:00
# build image for amd64 only
2021-11-14 00:47:59 +03:00
docker build -t flame -f .docker/Dockerfile .
2021-06-07 14:40:51 +03:00
2021-06-18 15:12:17 +03:00
# build multiarch image for amd64, armv7 and arm64
# building failed multiple times with 2GB memory usage limit so you might want to increase it
docker buildx build \
--platform linux/arm/v7,linux/arm64,linux/amd64 \
2021-11-14 00:47:59 +03:00
-f .docker/Dockerfile.multiarch \
2021-06-18 15:12:17 +03:00
-t flame:multiarch .
```
2021-06-28 02:33:27 +03:00
#### Docker-Compose
2021-08-03 11:22:55 +03:00
2021-06-28 02:33:27 +03:00
```yaml
2021-12-02 18:43:13 +03:00
version: '3.6'
2021-06-28 02:33:27 +03:00
services:
flame:
2021-12-02 18:43:13 +03:00
image: pawelmalak/flame
2021-06-28 02:33:27 +03:00
container_name: flame
volumes:
2021-12-02 18:43:13 +03:00
- /path/to/host/data:/app/data
- /var/run/docker.sock:/var/run/docker.sock # optional but required for Docker integration
2021-06-28 02:33:27 +03:00
ports:
- 5005:5005
2021-12-02 18:43:13 +03:00
secrets:
- password # optional but required for (1)
2021-11-14 00:47:59 +03:00
environment:
- PASSWORD=flame_password
2021-12-02 18:43:13 +03:00
- PASSWORD_FILE=/run/secrets/password # optional but required for (1)
2021-06-28 02:33:27 +03:00
restart: unless-stopped
2021-12-02 18:43:13 +03:00
# optional but required for Docker secrets (1)
secrets:
password:
file: /path/to/secrets/password
2021-06-28 02:33:27 +03:00
```
2021-11-20 02:54:34 +03:00
##### Docker Secrets
2021-12-02 18:43:13 +03:00
All environment variables can be overwritten by appending `_FILE` to the variable value. For example, you can use `PASSWORD_FILE` to pass through a docker secret instead of `PASSWORD` . If both `PASSWORD` and `PASSWORD_FILE` are set, the docker secret will take precedent.
```bash
# ./secrets/flame_password
my_custom_secret_password_123
# ./docker-compose.yml
secrets:
password:
file: ./secrets/flame_password
```
2021-11-20 02:54:34 +03:00
2021-08-17 11:32:15 +03:00
#### Skaffold
```sh
# use skaffold
skaffold dev
```
2021-06-21 14:59:17 +03:00
### Without Docker
2021-08-03 11:22:55 +03:00
2021-06-21 14:59:17 +03:00
Follow instructions from wiki: [Installation without Docker ](https://github.com/pawelmalak/flame/wiki/Installation-without-docker )
2021-11-14 00:47:59 +03:00
## Development
2021-08-03 11:22:55 +03:00
2021-11-14 00:47:59 +03:00
### Technology
2021-06-08 13:51:50 +03:00
2021-11-14 00:47:59 +03:00
- Backend
- Node.js + Express
- Sequelize ORM + SQLite
- Frontend
- React
- Redux
- TypeScript
- Deployment
- Docker
- Kubernetes
### Creating dev environment
```sh
# clone repository
git clone https://github.com/pawelmalak/flame
cd flame
# run only once
npm run dev-init
2021-06-08 13:51:50 +03:00
2021-11-14 00:47:59 +03:00
# start backend and frontend development servers
npm run dev
```
2021-06-08 13:51:50 +03:00
2021-11-14 00:47:59 +03:00
## Screenshots
2021-06-08 13:51:50 +03:00
2021-11-14 00:47:59 +03:00
![Apps screenshot ](.github/apps.png )
2021-08-03 11:22:55 +03:00
2021-11-14 00:47:59 +03:00
![Bookmarks screenshot ](.github/bookmarks.png )
2021-06-21 14:59:17 +03:00
2021-11-14 00:47:59 +03:00
![Settings screenshot ](.github/settings.png )
2021-06-08 13:51:50 +03:00
2021-11-14 01:28:43 +03:00
![Themes screenshot ](.github/themes.png )
2021-06-11 16:33:06 +03:00
## Usage
2021-08-03 11:22:55 +03:00
2021-11-14 00:47:59 +03:00
### Authentication
Visit [project wiki ](https://github.com/pawelmalak/flame/wiki/Authentication ) to read more about authentication
2021-06-24 13:53:45 +03:00
### Search bar
2021-08-03 11:22:55 +03:00
2021-06-25 11:42:44 +03:00
#### Searching
2021-08-03 11:22:55 +03:00
2021-11-15 01:20:37 +03:00
The default search setting is to search through all your apps and bookmarks. If you want to search using specific search engine, you need to type your search query with selected prefix. For example, to search for "what is docker" using google search you would type: `/g what is docker` .
2021-06-25 11:42:44 +03:00
2021-11-05 18:39:42 +03:00
For list of supported search engines, shortcuts and more about searching functionality visit [project wiki ](https://github.com/pawelmalak/flame/wiki/Search-bar ).
2021-06-24 13:53:45 +03:00
2021-06-21 14:59:17 +03:00
### Setting up weather module
2021-08-03 11:22:55 +03:00
2021-06-21 14:59:17 +03:00
1. Obtain API Key from [Weather API ](https://www.weatherapi.com/pricing.aspx ).
> Free plan allows for 1M calls per month. Flame is making less then 3K API calls per month.
2. Get lat/long for your location. You can get them from [latlong.net ](https://www.latlong.net/convert-address-to-lat-long.html ).
3. Enter and save data. Weather widget will now update and should be visible on Home page.
2021-08-04 23:19:35 +03:00
### Docker integration
In order to use the Docker integration, each container must have the following labels:
```yml
labels:
- flame.type=application # "app" works too
- flame.name=My container
- flame.url=https://example.com
2021-11-05 18:39:42 +03:00
- flame.icon=icon-name # optional, default is "docker"
2021-09-29 23:26:12 +03:00
# - flame.icon=custom to make changes in app. ie: custom icon upload
```
2021-11-10 18:45:30 +03:00
> "Use Docker API" option must be enabled for this to work. You can find it in Settings > Docker
2021-10-06 23:22:18 +03:00
2021-11-05 18:39:42 +03:00
You can also set up different apps in the same label adding `;` between each one.
2021-09-29 23:26:12 +03:00
```yml
labels:
- flame.type=application
- flame.name=First App;Second App
- flame.url=https://example1.com;https://example2.com
- flame.icon=icon-name1;icon-name2
2021-08-04 23:19:35 +03:00
```
2021-10-06 23:22:18 +03:00
If you want to use a remote docker host follow this instructions in the host:
- Open the file `/lib/systemd/system/docker.service` , search for `ExecStart` and edit the value
```text
ExecStart=/usr/bin/dockerd -H tcp://0.0.0.0:${PORT} -H unix:///var/run/docker.sock
```
>The above command will bind the docker engine server to the Unix socket as well as TCP port of your choice. “0.0.0.0” means docker-engine accepts connections from all IP addresses.
- Restart the daemon and Docker service
```shell
sudo systemctl daemon-reload
sudo service docker restart
```
- Test if it is working
```shell
curl http://${IP}:${PORT}/version
```
2021-08-04 23:19:35 +03:00
2021-08-17 11:32:15 +03:00
### Kubernetes integration
In order to use the Kubernetes integration, each ingress must have the following annotations:
```yml
metadata:
annotations:
- flame.pawelmalak/type=application # "app" works too
- flame.pawelmalak/name=My container
- flame.pawelmalak/url=https://example.com
2021-11-05 18:39:42 +03:00
- flame.pawelmalak/icon=icon-name # optional, default is "kubernetes"
2021-08-17 11:32:15 +03:00
```
2021-11-10 18:45:30 +03:00
> "Use Kubernetes Ingress API" option must be enabled for this to work. You can find it in Settings > Docker
2021-08-17 11:32:15 +03:00
2021-11-08 17:42:32 +03:00
### Import HTML Bookmarks (Experimental)
- Requirements
- python3
- pip packages: Pillow, beautifulsoup4
- Backup your `db.sqlite` before running script!
- Known Issues:
- generated icons are sometimes incorrect
2021-11-20 02:54:34 +03:00
2021-11-08 17:42:32 +03:00
```bash
pip3 install Pillow, beautifulsoup4
cd flame/.dev
python3 bookmarks_importer.py --bookmarks < path to bookmarks . html > --data < path to flame data folder >
```
2021-11-05 18:39:42 +03:00
### Custom CSS and themes
2021-08-03 11:22:55 +03:00
2021-11-08 16:00:57 +03:00
See project wiki for [Custom CSS ](https://github.com/pawelmalak/flame/wiki/Custom-CSS ) and [Custom theme with CSS ](https://github.com/pawelmalak/flame/wiki/Custom-theme-with-CSS ).