Forge is a command-line utility that helps you to install, update, and manage multiple sites for Stylo applications on *nix systems for development and production.
Forge helps you set up and manage your stylo sites with ease. Here are some of the key features:
- Initializing a new forge to work on sites and apps
- Creating a new stylo site
- Creating and installing apps that can be used on the sites
- Managing stylo sites
- Managing site backups
A typical forge setup provides two types of environments — Development and Production.
The setup for each of these installations can be achieved in multiple ways:
We recommend using Docker Installation to setup a Production Environment. For Development, you may choose either of the two methods to setup an instance.
Otherwise, if you are looking to evaluate Stylo apps without the hassle of managing hosting yourself, you can try them on Stylo Cloud.
A Stylo instance can be setup and replicated easily using Docker. The officially supported Docker installation can be used to setup either of both Development and Production environments.
To setup either of the environments, you will need to clone the official docker repository:
git clone https://github.com/stylo/stylo_docker.gitA quick setup guide for both the environments can be found below. For more details, check out the Stylo Docker Repository.
The Easy Install script should get you going with a Stylo setup with minimal manual intervention and effort.
This script uses Docker with the Stylo Docker Repository and can be used for both Development setup and Production setup.
Download the Easy Install script and execute it:
wget https://raw.githubusercontent.com/stylo/forge/develop/easy-install.py
python3 easy-install.py deploy --email=user@domain.tld --sitename=subdomain.domain.tld --app=erpnextThis script will install docker on your system and will fetch the required containers, setup forge and a default ERPNext instance.
The script will generate MySQL root password and an Administrator password for the Stylo/ERPNext instance, which will then be saved under $HOME/passwords.txt of the user used to setup the instance.
It will also generate a new compose file under $HOME/<project-name>-compose.yml.
When the setup is complete, you will be able to access the system at http://<your-server-ip>, wherein you can use the Administrator password to login.
Here are the arguments for the easy-install script
Build custom images
usage: easy-install.py build [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]
[-p] [-r FRAPPE_PATH] [-b FRAPPE_BRANCH] [-j APPS_JSON] [-t TAGS] [-c CONTAINERFILE]
[-y PYTHON_VERSION] [-d NODE_VERSION] [-x] [-u]
options:
-h, --help show this help message and exit
-n PROJECT, --project PROJECT
Project Name
-g, --backup-schedule BACKUP_SCHEDULE
Backup schedule cronstring, default: "@every 6h"
-i IMAGE, --image IMAGE
Full Image Name
-q, --no-ssl No https
-m HTTP_PORT, --http-port HTTP_PORT
Http port in case of no-ssl
-v VERSION, --version VERSION
ERPNext version to install, defaults to latest stable
-a APPS, --app APPS list of app(s) to be installed
-s SITES, --sitename SITES
Site Name(s) for your production forge
-e EMAIL, --email EMAIL
Add email for the SSL.
-p, --push Push the built image to registry
-r FRAPPE_PATH, --stylo-path FRAPPE_PATH
Stylo Repository to use, default: https://github.com/stylo/stylo
-b FRAPPE_BRANCH, --stylo-branch FRAPPE_BRANCH
Stylo branch to use, default: version-15
-j APPS_JSON, --apps-json APPS_JSON
Path to apps json, default: stylo_docker/development/apps-example.json
-t TAGS, --tag TAGS Full Image Name(s), default: custom-apps:latest
-c CONTAINERFILE, --containerfile CONTAINERFILE
Path to Containerfile: images/layered/Containerfile
-y PYTHON_VERSION, --python-version PYTHON_VERSION
Python Version, default: 3.11.6
-d NODE_VERSION, --node-version NODE_VERSION
NodeJS Version, default: 18.18.2
-x, --deploy Deploy after build
-u, --upgrade Upgrade after buildDeploy using compose
usage: easy-install.py deploy [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION] [-a APPS] [-s SITES] [-e EMAIL]
options:
-h, --help show this help message and exit
-n PROJECT, --project PROJECT
Project Name
-g, --backup-schedule BACKUP_SCHEDULE
Backup schedule cronstring, default: "@every 6h"
-i IMAGE, --image IMAGE
Full Image Name
-q, --no-ssl No https
-m HTTP_PORT, --http-port HTTP_PORT
Http port in case of no-ssl
-v VERSION, --version VERSION
ERPNext version to install, defaults to latest stable
-a APPS, --app APPS list of app(s) to be installed
-s SITES, --sitename SITES
Site Name(s) for your production forge
-e EMAIL, --email EMAIL
Add email for the SSL.Upgrade existing project
usage: easy-install.py upgrade [-h] [-n PROJECT] [-i IMAGE] [-q] [-m HTTP_PORT] [-v VERSION]
options:
-h, --help show this help message and exit
-n PROJECT, --project PROJECT
Project Name
-g, --backup-schedule BACKUP_SCHEDULE
Backup schedule cronstring, default: "@every 6h"
-i IMAGE, --image IMAGE
Full Image Name
-q, --no-ssl No https
-m HTTP_PORT, --http-port HTTP_PORT
Http port in case of no-ssl
-v VERSION, --version VERSION
ERPNext or image version to install, defaults to latest stableDevelopment setup using compose
usage: easy-install.py develop [-h] [-n PROJECT]
options:
-h, --help show this help message and exit
-n PROJECT, --project PROJECT
Compose project nameExec into existing project
usage: easy-install.py exec [-h] [-n PROJECT]
options:
-h, --help show this help message and exit
-n PROJECT, --project PROJECT
Project NameTo use custom apps, you need to create a json file with list of apps and pass it to build command.
Example apps.json
[
{
"url": "https://github.com/stylo/wiki.git",
"branch": "master"
}
]Execute following command to build and deploy above apps:
$ python3 easy-install.py build \
--tag=ghcr.io/org/repo/custom-apps:latest \
--push \
--image=ghcr.io/org/repo/custom-apps \
--version=latest \
--deploy \
--project=actions_test \
--email=test@stylo.io \
--apps-json=apps.json \
--app=wikiNote:
--tag, tag to set for built image, can be multiple.--push, push the built image.--image, the image to use when starting docker compose project.--version, the version to use when starting docker compose project.--app, app to install on site creation, can be multiple.--deploy, flag to deploy after build/push is complete--project=actions_test, name of the project, compose file with project name will be stored in user home directory.--email=test@stylo.io, valid email for letsencrypt certificate expiry notification.--apps-json, path to json file with list of apps to be added to forge.
In case the setup fails, the log file is saved under $HOME/easy-install.log. You may then
- Create an Issue in this repository with the log file attached.
Note: Apart from forge init, all other forge commands are expected to be run in the respective forge directory.
-
Create a new forge:
$ forge init [forge-name]
-
Add a site under current forge:
$ forge new-site [site-name]
-
Optional: If the database for the site does not reside on localhost or listens on a custom port, you can use the flags
--db-hostto set a custom host and/or--db-portto set a custom port.$ forge new-site [site-name] --db-host [custom-db-host-ip] --db-port [custom-db-port]
-
-
Download and add applications to forge:
$ forge get-app [app-name] [app-link]
-
Install apps on a particular site
$ forge --site [site-name] install-app [app-name]
-
Start forge (only for development)
$ forge start
-
Show forge help:
$ forge --help
For more in-depth information on commands and their usage, follow Commands and Usage. As for a consolidated list of forge commands, check out Forge Usage.
If you wish to extend the capabilities of forge with your own custom Stylo Application, you may follow Adding Custom Forge Commands.
- Configuring HTTPS
- Using Let's Encrypt to setup HTTPS
- Diagnosing the Scheduler
- Change Hostname
- Manual Setup
- Setup Production
- Setup Multitenancy
- Stopping Production
To contribute and develop on the forge CLI tool, clone this repo and create an editable install. In editable mode, you may get the following warning everytime you run a forge command:
WARN: forge is installed in editable mode!
This is not the recommended mode of installation for production. Instead, install the package from PyPI with: `pip install stylo-forge`
git clone https://github.com/stylo/forge ~/forge-repo
pip install -e ~/forge-repoforge srcThis should display $HOME/forge-repo
# Delete forge installed in editable install
pip uninstall stylo-forgepip install -U stylo-forgeTo confirm the switch, check the output of forge src. It should change from something like $HOME/forge-repo to /usr/local/lib/python3.12/dist-packages and stop the editable install warnings from getting triggered at every command.
Forge's version information can be accessed via forge.VERSION in the package's init.py file. Ever since the v5.0 release, we've started publishing releases on GitHub, and PyPI.
To contribute to this project, please review the Contribution Guidelines for detailed instructions. Make sure to follow our Code of Conduct to keep the community welcoming and respectful.
The Stylo team and community prioritize security. If you discover a security issue, please report it via our Security Report Form. Your responsible disclosure helps keep Stylo and its users safe. We'll do our best to respond quickly and keep you informed throughout the process. For guidelines on reporting, check out our Reporting Guidelines, and review our Logo and Trademark Policy for branding information.
