From 6ff072a3221c9194a1f2263ee03132e9be7df589 Mon Sep 17 00:00:00 2001
From: Iskren Hadzhinedev <iskren.hadzhinedev@x3me.net>
Date: Mon, 1 Apr 2024 09:49:25 +0300
Subject: [PATCH] setup-wizard command instructions for initial database
 objects

Implements #889.
---
 docs/install/manually.md | 94 +++++++++-------------------------------
 1 file changed, 21 insertions(+), 73 deletions(-)

diff --git a/docs/install/manually.md b/docs/install/manually.md
index d38430b44..90dafda01 100644
--- a/docs/install/manually.md
+++ b/docs/install/manually.md
@@ -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).
 
@@ -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:
@@ -61,7 +61,6 @@ chown -R www-data: bootstrap/cache storage
 
 ## Initial Setup and Dependencies
 
-
 ### Dependencies
 
 Install the required PHP libraries:
@@ -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
@@ -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
@@ -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
-USEREMAIL=your@email.address
-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
-IXPPEEREMAIL=peering@example.com
-IXPNOCPHONE=12345678
-IXPNOCEMAIL=noc@example.com
-IXPWWW="http://www.example.com"
-USERNAME=jbloggs
-USEREMAIL=jbloggs@example.com
 ```
-
-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:
@@ -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
@@ -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).**