Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix grammar and use correct markdown in readme. #2

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Fix grammar and use correct markdown in readme. #2

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bbd8481
Improve README.md
ajh123 Apr 21, 2024
8b17ad2
Add links in README.md
ajh123 Apr 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 46 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,74 +1,89 @@
# UISP-Tools

UISP-Tools is an open-source node server that extend the functionality of [UISP](https://uisp.ui.com/).
This Node.js application runs in a seperate docker instance will interface to your instance of UISP using an Application Key using the UISP API's.
CRM [Read more](https://ucrm.docs.apiary.io/#).
NMS [Read more](https://<your-uisp-hostname>/nms/api-docs/).
This Node.js application runs in a seperate docker instance that will interface to your instance of UISP using an Application Key using the UISP API's.
CRM [API docs](https://ucrm.docs.apiary.io/#).
NMS [API docs](https://unms.docs.apiary.io/#).

UISP-Tools is compatible with UCRM 2.10.0+

## There are Now two install first is the easiest and will work with a Cloud Hosted and Self Hosted the Second Method only will Self Hosted but becasue it runs inside of UISP Docker Compse it will be able to access the UISP Postgres Directly
**There are now two install methods, the [first one](#method-one) is the easiest and will work with a Cloud Hosted and Self Hosted, the [second method](#method-two) only will Self Hosted but becasue it runs with Docker inside of UISP; it will be able to access the UISP Postgres Directly**

## Method One

#Method One (Cloud Hosted and Self Hosted) Running as a seperate Docker Container on either sperate server or same server as UISP
> [!IMPORTANT]
> This works with Cloud Hosted and Self Hosted, it runs as a seperate Docker container on either a sperate server or the same server as UISP

### How does it work?

## How does it work?
* uisptools docker container is created and runs on a seperate ip or port and url as UISP
* uisptools docker container is configured to use the UISP API's via API Key to access the UISP data via built in UISP API functions

## How to install
### How to install

#### Step 1: Install Docker on the server

### Step 1: Install Docker on the server
#### Step 2: Add your account to the docker group and log out and back in or run newgrp groupName

### Step 2: Add your account to the docker group and log out and back in or run newgrp groupName
```
sudo usermod -a -G docker $USER
newgrp groupName
```

'''
#### Step 3: Download the `installUispToolsStandAlone.sh` script from github

### Step 3: Download the installUispToolsStandAlone.sh script from github
```
curl -H 'Cache-Control: no-cache, no-store' -sL https://raw.githubusercontent.com/Andrewiski/UISP-Tools/main/dockerCompose/installUispToolsStandAlone.sh -o installUispToolsStandAlone.sh
```

### Step 4: Run the installUispToolsStandAlone.sh script
#### Step 4: Run the `installUispToolsStandAlone.sh` script

```
./installUispToolsStandAlone.sh -alias uisptools -googleapikey "AIAASSSrB1Ek-000000-0000000" -installdir "/home/$USER/uisptools" -httpport 46080 -httpsport 46443 -nocreateuser
./installUispToolsStandAlone.sh -alias uisptools -googleapikey "AIAASSSrB1Ek-000000-0000000" -installdir "/home/$USER/uisptools" -httpport 46080 -httpsport 46443 -nocreateuser
```

### Step 5: Edit the config.json file to add your UISP API Key and Set the UNMS and UCRM URLs
#### Step 5: Edit the `config.json1 file to add your UISP API Key and Set the UNMS and UCRM URLs

```
nano /home/$USER/uisptools/config/config.json
nano /home/$USER/uisptools/config/config.json
```

### Step 6: Open the UISP-Tools in your browser, login using your UISP NMS credentials, note that the single login will allow you to login using CRM but not give you access to the ADMIN tools.
#### Step 6: Open the UISP-Tools in your browser, login using your UISP NMS credentials, note that the single login will allow you to login using CRM but not give you access to the ADMIN tools.

```
http://<your-uisptools-hostname>:46080
http://<your-uisptools-hostname>:46080
```

## To Upgrade UISP-Tools run the installUispToolsStandAlone.sh script with the -upgrade flag
### To upgrade UISP-Tools run the `installUispToolsStandAlone.sh` script with the -upgrade flag

```
./installUispToolsStandAlone.sh -alias uisptools -googleapikey "AIAASSSrB1Ek-000000-0000000" -installdir "/home/$USER/uisptools" -httpport 46080 -httpsport 46443 -nocreateuser -upgrade
./installUispToolsStandAlone.sh -alias uisptools -googleapikey "AIAASSSrB1Ek-000000-0000000" -installdir "/home/$USER/uisptools" -httpport 46080 -httpsport 46443 -nocreateuser -upgrade
```

## Optional Install NGIX to handle SSL and Reverse Proxy
```
sudo apt-get install nginx
sudo nano /etc/nginx/sites-available/uisptools
### Optional. Install NGINX for reverse proxy and SSL

```
sudo apt-get install nginx
sudo nano /etc/nginx/sites-available/uisptools
```

#Method Two (Self Hosted Only) Running Inside of UISP Docker Compose by Injecting the UISP Tools Docker Containers into the UISP Docker Compose
## Method Two

> [!IMPORTANT]
> This will only works for self hosted UISP instances, it runs with Docker on the UISP server by injecting the UISP Tools Docker containers into the UISP Docker Compose file.

### How does it work?

## How does it work?
* uisptools docker services are added to the UISP docker-compose.yaml file that is created during the UISP install process located at /home/unms/app/docker-compose.yml
* next the /uisptools path is added to the unms-nginx conf.d so that it can accessed using the UNMS url /uisp
* plugins can be added by copying them to the config/plugin folder and adding them to the plugins section of config.json file
* all of the uisptools reside in a completly seperate paths as well as seperate containers so easy to remove and upgrade


## How to install (Could use some help creating an install.sh script to make this easier)
### How to install

*(Could use some help creating an install.sh script to make this easier)*

```
# Create a password for the unms user
sudo passwd unms
Expand Down Expand Up @@ -131,20 +146,23 @@ docker-compose up -d

Should be ablle to get the default website to open by visiting https://uispserver/uisptools


## How to edit the Mongo Database

I use the free Windows app Studio 3T and connect to the mongo instance using ssh and then authentication using the uisptools and password set in docker-compose.yaml.
Note that username password combo if changed needs to be updated in the /home/unms/uisptools/config/config.json as well in the mongodb url


## Plugins General Usage and Warnings

* Installing uisptools can allow any NMS superadmin to make any nms api call exposed this includes Posts and Deletes via urls using the generic passthrough this can be disabled with a config option. The user does need to using the uisptools login and have an active short lived access token
* Any plugin can be copied and extended by coping to the config/plugins folder, config/plugins is served before /plugins this way any and all plugins can be extended

## How can I contribute?

* This application are under GNU General Public License v3.0 enabling anyone to contribute any upgrades or create whole new ones
* Propose any Pull Request in this repository.
* See the documentation below.

## Disclaimer
The software is provided "as is", without any warranty of any kind. Please read [LICENSE](https://raw.githubusercontent.com/Andrewiski/UISP-Tools/main/LICENSE) for further details

The software is provided "as is", without any warranty of any kind. Please read [LICENSE](./LICENSE) for further details