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

Update the manual installation documentation with the ixp-manager:setup-wizard command #27

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update the manual installation documentation with the ixp-manager:setup-wizard command #27

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
94 changes: 21 additions & 73 deletions docs/install/manually.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@ IXP Manager tries to stay current in terms of technology. Typically, this means

The current requirements for the web application are:

* a Linux / BSD host - **all documentation and videos relate to Ubuntu LTS**.
* MySQL 8.
* Apache / Nginx / etc.
* PHP >= 8.0. **Note that IXP Manager >= v6.0 will not run on older versions of PHP.**
* Memcached - optional but recommended.
- a Linux / BSD host - **all documentation and videos relate to Ubuntu LTS**.
- MySQL 8.
- Apache / Nginx / etc.
- PHP >= 8.0. **Note that IXP Manager >= v6.0 will not run on older versions of PHP.**
- Memcached - optional but recommended.

To complete the installation using the included config/scripts, you will also need to have installed git (`apt install git`) and a number of PHP extensions (see the example `apt install` below).

Expand All @@ -32,7 +32,7 @@ apt install -qy apache2 php8.0 php8.0-intl php8.0-rrd php8.0-cgi php8.0-cli
mysql-client php8.0-mysql memcached snmp php8.0-mbstring php8.0-xml php8.0-gd \
php8.0-bcmath bgpq3 php8.0-memcache unzip php8.0-zip git php8.0-yaml \
php8.0-ds libconfig-general-perl libnetaddr-ip-perl mrtg libconfig-general-perl \
libnetaddr-ip-perl rrdtool librrds-perl curl composer
libnetaddr-ip-perl rrdtool librrds-perl curl composer
```

Do note that Ubuntu 20.04 LTS comes with PHP 7.4 so you must enable Ondřej Surý's excellent [Ubuntu PHP PPA](https://launchpad.net/~ondrej/+archive/ubuntu/php) (and maybe [buy him a pint](https://deb.sury.org/#donate)). This can be enabled with:
Expand Down Expand Up @@ -61,7 +61,6 @@ chown -R www-data: bootstrap/cache storage

## Initial Setup and Dependencies


### Dependencies

Install the required PHP libraries:
Expand All @@ -70,7 +69,6 @@ First you will need Composer v2 but v1 ships with Ubuntu 20.04. Composer is PHP'

We assume you downloaded it to `$IXPROOT` as `composer.phar` in the following:


```sh
cd $IXPROOT
php composer.phar install --no-dev --prefer-dist
Expand All @@ -80,7 +78,6 @@ php artisan key:generate

## Database Setup


Use whatever means you like to create a database and user for IXP Manager. For example:

```mysql
Expand Down Expand Up @@ -122,66 +119,20 @@ Edit `$IXPROOT/.env` and review and set/change all parameters. Hopefully this is

### Initial Database Objects

Use the `php artisan ixp-manager:setup-wizard` command to setup the minimum required database objects for your installation.
You may use command-line options to provide the required data (useful for unnatended setups), or use it interactively.

Using the settings you edited in `.env` we'll create some database objects. [Yes, a setup wizard needs to be built!].

First let's create the password for the admin user. The following will create a secure random password and hash it with bcrypt:
Note that the admin password **cannot** be provided from the command-line to prevent it leaking in your shell's history records.
Use the special environment variable `IXP_SETUP_ADMIN_PASSWORD` to set it in your automation scripts.

```sh
cd $IXPROOT
source .env
USERNAME=admin
[email protected]
IXPM_ADMIN_PW="$( openssl rand -base64 12 )"
ADMIN_PW_SALT="$( openssl rand -base64 16 )"
HASH_PW=$( php -r "echo escapeshellarg( crypt( '${IXPM_ADMIN_PW}', sprintf( '\$2a\$%02d\$%s', 10, substr( '${ADMIN_PW_SALT}', 0, 22 ) ) ) );" )
echo Your password is: $IXPM_ADMIN_PW

NAME="Joe"
IXPNAME=SCIX
IXPSNAME=SCIX
IXPASN=65500
[email protected]
IXPNOCPHONE=12345678
[email protected]
IXPWWW="http://www.example.com"
USERNAME=jbloggs
[email protected]
```

The following is taken from the IXP Manager installation script:


```mysql
mysql -h $DB_HOST -u $DB_USERNAME "-p${DB_PASSWORD}" $DB_DATABASE <<END_SQL
INSERT INTO infrastructure ( name, shortname, isPrimary, created_at, updated_at )
VALUES ( 'Infrastructure #1', '#1', 1, NOW(), NOW() );
SET @infraid = LAST_INSERT_ID();

INSERT INTO company_registration_detail ( registeredName, created_at, updated_at ) VALUES ( '${IXPNAME}', NOW(), NOW() );
SET @crdid = LAST_INSERT_ID();

INSERT INTO company_billing_detail ( billingContactName, invoiceMethod, billingFrequency, created_at, updated_at )
VALUES ( '${NAME}', 'EMAIL', 'NOBILLING', NOW(), NOW() );
SET @cbdid = LAST_INSERT_ID();

INSERT INTO cust ( name, shortname, type, abbreviatedName, autsys, maxprefixes, peeringemail, nocphone, noc24hphone,
nocemail, nochours, nocwww, peeringpolicy, corpwww, datejoin, status, activepeeringmatrix, isReseller,
company_registered_detail_id, company_billing_details_id, created_at, updated_at )
VALUES ( '${IXPNAME}', '${IXPSNAME}', 3, '${IXPSNAME}', '${IXPASN}', 100, '${IXPPEEREMAIL}', '${IXPNOCPHONE}',
'${IXPNOCPHONE}', '${IXPNOCEMAIL}', '24x7', '', 'mandatory', '${IXPWWW}', NOW(), 1, 1, 0, @crdid, @cbdid, NOW(), NOW() );
SET @custid = LAST_INSERT_ID();

INSERT INTO user ( custid, name, username, password, email, privs, disabled, created_at, updated_at )
VALUES ( @custid, '${NAME}', '${USERNAME}', ${HASH_PW}, '${USEREMAIL}', 3, 0, NOW(), NOW() );
SET @userid = LAST_INSERT_ID();

INSERT INTO customer_to_users ( customer_id, user_id, privs, created_at, updated_at )
VALUES ( @custid, @userid, 3, NOW(), NOW() );

INSERT INTO contact ( custid, name, email, created_at, updated_at )
VALUES ( @custid, '${NAME}', '${USEREMAIL}', NOW(), NOW() );
END_SQL
ixp-manager:setup-wizard options:
-N, --name[=NAME] The name of the admin user
-U, --username[=USERNAME] The username of the admin user
-E, --email[=EMAIL] The email of the admin user
-A, --asn[=ASN] The ASN of your IXP
-I, --infrastructure[=INFRASTRUCTURE] The name of your primary infrastructure
-C, --company-name[=COMPANY-NAME] The name of your company
```

And finally seed the database:
Expand All @@ -205,7 +156,6 @@ chmod -R u+rwX storage/ bootstrap/cache/

## Setting Up Apache


Here is a sample virtual hosts file for IXP Manager (replace `{$IXPROOT}` as appropriate!):

```apache
Expand Down Expand Up @@ -237,15 +187,13 @@ service apache2 restart

# Congratulations!


Your new IXP Manager installation should be accessible via your server's IP address using the username (`$USERNAME`) and password (`$IXPM_ADMIN_PW`) you set above.

If you plan to use this in production, you should:

* secure your server with an iptables firewall
* install an SSL certificate and redirect HTTP access to HTTPS
* complete the installation of the many features of IXP Manager such as route server generation, member stats, peer to peer graphs, etc.
* PLEASE TELL US! We'd like to add you to the users list at https://www.ixpmanager.org/community/world-map - just complete the form there or drop us an email to `operations <at> inex <dot> ie`.

- secure your server with an iptables firewall
- install an SSL certificate and redirect HTTP access to HTTPS
- complete the installation of the many features of IXP Manager such as route server generation, member stats, peer to peer graphs, etc.
- PLEASE TELL US! We'd like to add you to the users list at https://www.ixpmanager.org/community/world-map - just complete the form there or drop us an email to `operations <at> inex <dot> ie`.

**What next? See our [post-install / next steps document here](next-steps.md).**