diff --git a/CHANGELOG.md b/CHANGELOG.md index d0b168d..53057e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ v1.7 - Fix FLEXIAPI-250 Allow Spaces to be declared without a subdomain - Fix FLEXIAPI-252 Update the hCaptcha Laravel library, use file instead of cookies to store the session to prevent empty errors bags - Fix FLEXIAPI-254 Allow no data on POST requests to not trigger the ValidateJSON middleware +- Fix FLEXIAPI-255 Create a INSTALL.md tutorial and log FlexisipPusherConnector errors v1.6 ---- diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..49c52da --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,165 @@ +# DotEnv configuration + +FlexiAPI relies on [DotEnv](https://github.com/vlucas/phpdotenv) to be configured. This configuration can be accessed using the existing `.env` file that can be itself overwritten by an environnement variables. + +Thoses variables can then be set using Docker-Compose, a bash script or a web-server. + +If you're installing FlexiAPI from the RPM package you can find the configuration file at `/etc/flexisip-account-manager/flexiapi.env`. + +# 1.a Manual setup + +Clone the repository, install the dependencies and generate a key. + + composer install --no-dev + php artisan key:generate + +Then configure the database connection in the `.env` file (from the `.env.example` one). And migrate the tables. The first migration *MUST* be run on an empty database. + + php artisan migrate + +You can also run the test suit using `phpunit`. + +To know more about the web server configuration part, you can directly [visit the official Laravel installation documentation](https://laravel.com/docs/). + +# 1.b Packages setup + +FlexiAPI is packaged for Debian and RedHat, you can setup those repositories using the Flexisip documentation https://wiki.linphone.org/xwiki/wiki/public/view/Flexisip/1.%20Installation/#HInstallationfromourrepositories + + yum install bc-flexisip-account-manager # For RedHat distributions + apt install bc-flexisip-account-manager # For Debian distributions + +# 2. Web server configuration + +The package will deploy a `flexisip-account-manager.conf` file in the apache2 configuration directory. +This file can be loaded and configured in your specific VirtualHost configuration. + +# 3. .env file configuration + +Complete all the other variables in the `.env` file or by overwritting them in your Docker or web-server configuration. + +## 3.1. Mandatory `APP_ROOT_HOST` variable + +`APP_ROOT_HOST` contains the HTTP host where your FlexiAPI is hosted (eg. `flexiapi.domain.tld` or directly `flexiapi-domain.tld`). + +This is the host that you'll define in the Apache or webserver VirtualHost: + + ServerName flexiapi-domain.tld + ServerAlias *.flexiapi-domain.tld + +If you are planning to manage several SIP domains (see Spaces bellow) a wildcard `ServerAlias` as above is required. + +## 3.2. For manual setups + +`APP_KEY` Can be set using the `php artisan key:generate` command. + +# 4. Spaces + +Since the 1.6 FlexiAPI can manage different SIP Domains on separate HTTP subdomains. + +A Space is defined as a specific HTTP subdomain of `APP_ROOT_HOST` and is linked to a specific SIP Domain. It is also possible to host one specific Space directly under `APP_ROOT_HOST`. + +By default administrator accounts in Spaces will only see the accounts of their own Space (that have the same SIP Domain). +However it is possible to define a Space as a "SuperSpace" allowing the admins to see all the other Spaces and accounts and create/edit/delete the other Spaces. + +## 4.1. Setup the first Space + +You will need to create the first Space manually, generally as a SuperSpace, after that the other Spaces can directly be created in your browser through the web panel. + + php artisan spaces:create-update {sip_domain} {host} {--super} + +For example: + + php artisan spaces:create-update company-sip-domain.tld flexiapi-domain.tld --super + php artisan spaces:create-update other-sip-domain.tld other.flexiapi-domain.tld + +## 5. Create a first administrator and finish the setup + +Create a first administator account: + + php artisan accounts:create-admin-account {-u|username=} {-p|password=} {-d|domain=} + +For example: + + php artisan accounts:create-admin-account admin strong_password my-company-sip-domain.tld + +You can now try to authenticate on the web panel and continue the setup using your admin account. + +# Other custom configurations + +## Multiple virtualhosts option + +In your web server configuration create several VirtualHosts that are pointing to the same FlexiAPI instance. +Using the environnement variables you can then configure FlexiAPI per instance. + +With Apache, use the [mod_env](https://httpd.apache.org/docs/2.4/mod/mod_env.html) module. + + SetEnv APP_NAME "VirtualHost One" + +On nginx use `fastcgi_param` to pass the parameter directly to PHP. + + location ~ [^/]\.php(/|$) { + … + include /etc/nginx/fastcgi_params; + fastcgi_param APP_NAME "VirtualHost Two"; + } + +> **Warning** Do not create a cache of your configuration (using `artisan config:cache`) if you have a multi-environnement setup. +> The cache is always having the priority on the variables set in the configuration files. + +## Multiple .env option + +To do so, configure several web servers virtualhosts and set a specific `APP_ENV` environnement variable in each of them. + +Note that if `APP_ENV` is not set FlexiAPI will directly use the default `.env` file. + +FlexiAPI will then try to load a custom configuration file with the following name `.env.$APP_ENV`. So for the previous example `.env.foobar`. + +You can then configure your instances with specific values. + + INSTANCE_COPYRIGHT="FooBar - Since 1997" + INSTANCE_INTRO_REGISTRATION="Welcome on the FooBar Server" + INSTANCE_CUSTOM_THEME=true + … + +## Custom theme + +If you set `INSTANCE_CUSTOM_THEME` to true, FlexiAPI will try to load a CSS file located in `public/css/$APP_ENV.style.css`. If the file doesn't exists it will fallback to `public/css/style.css`. + +You can find an example CSS file at `public/css/custom.style.css`. + +## Flexisip Push notifications pusher + +The API endpoint `POST /account_creation_tokens/send-by-push` uses the `flexisip_pusher` binary delivered by the [Flexisip](https://gitlab.linphone.org/BC/public/flexisip) project (and related package). You must configure the `APP_FLEXISIP_PUSHER_PATH` and `APP_FLEXISIP_PUSHER_FIREBASE_KEYSMAP` environnement variables to point to the correct binary. + + APP_FLEXISIP_PUSHER_PATH=/opt/belledonne-communications/bin/flexisip_pusher + +This binary will be executed under "web user" privileges. Ensure that all the related files required by `flexisip_pusher` can be accessed using this user account. + + /var/opt/belledonne-communications/log/flexisip/flexisip-pusher.log // Write permissions + /etc/flexisip/apn/*pem // Read permissions + +## SELinux restrictions + +If you are running on a CentOS/RedHat machine, please ensure that SELinux is correctly configured. + +Allow the webserver user to write in the `storage/` directory: + + chcon -R -t httpd_sys_rw_content_t storage/ + +Don't forget to make this change persistent if the directory may be relabeled : + + semanage fcontext -a -t httpd_sys_rw_content_t storage/ + +You can use the restorecon command to verify that this is working : + + restorecon storage/ + +If your database is located on a remote machine, you should also allow your webserver user to connect to remote hosts: + + semanage port -a -t http_port_t -p tcp 3306 // Open remote connections on the MySQL port for example + setsebool -P httpd_can_network_connect 1 // Allow remote network connected + setsebool -P httpd_can_network_connect_db 1 // Allow remote database connection + +If you are planning to send emails using your account manager: + + setsebool -P httpd_can_sendmail 1 // Allow email to be sent diff --git a/Makefile b/Makefile index 6a03cd0..2307b63 100644 --- a/Makefile +++ b/Makefile @@ -38,6 +38,7 @@ package-common: cp -R --parents flexiapi/**/* $(OUTPUT_DIR)/flexisip-account-manager/ cp flexiapi/composer* $(OUTPUT_DIR)/flexisip-account-manager/flexiapi/ cp README.md $(OUTPUT_DIR)/flexisip-account-manager/ + cp INSTALL.md $(OUTPUT_DIR)/flexisip-account-manager/ cp flexiapi/.env.example $(OUTPUT_DIR)/flexisip-account-manager/flexiapi/.env.example cp flexiapi/artisan $(OUTPUT_DIR)/flexisip-account-manager/flexiapi/ cp flexiapi/phpunit.xml $(OUTPUT_DIR)/flexisip-account-manager/flexiapi/ diff --git a/README.md b/README.md index 31b566d..e10f69f 100644 --- a/README.md +++ b/README.md @@ -21,122 +21,7 @@ Once deployed you can have access to the global and API documentation on the `/a # Setup -## DotEnv configuration - -FlexiAPI relies on [DotEnv](https://github.com/vlucas/phpdotenv) to be configured. This configuration can be accessed using the existing `.env` file that can be itself overwritten by an environnement variables. - -Thoses variables can then be set using Docker-Compose, a bash script or a web-server for example. - -If you're installing FlexiAPI from the RPM package you can find the configuration file at `/etc/flexisip-account-manager/flexiapi.env`. - -## Manual setup - -Clone the repository, install the dependencies and generate a key. - - composer install --no-dev - php artisan key:generate - -Then configure the database connection in the `.env` file (from the `.env.example` one). And migrate the tables. The migration *MUST* be run on an empty database. The `.env` file will be available at the root of the project or often located in `/etc/flexisip-account-manager` in packaged versions. - - php artisan migrate - -You can also run the test suit using `phpunit`. - -To know more about the web server configuration part, you can directly [visit the official Laravel installation documentation](https://laravel.com/docs/8.x). - -### Apache2 server configuration - -The package will deploy a `flexisip-account-manager.conf` file in the apache2 configuration directory. -This file can be loaded and configured in your specific VirtualHost configuration. - -### Configure the .env file - -Complete all the other variables in the `.env` file or by overwritting them in your Docker or web-server configuration: -- The OVH SMS connector -- SMTP configuration -- App name, SIP domain… - -### Multi instances environement - -FlexiAPI can also handle multi domains setup. - -#### Multiple virtualhosts option - -In your web server configuration create several virtualhosts that are pointing to the same FlexiAPI instance. -Using the environnement variables you can then configure FlexiAPI per instance. - -With Apache, use the [mod_env](https://httpd.apache.org/docs/2.4/mod/mod_env.html) module. - - SetEnv APP_NAME "VirtualHost One" - -On nginx use `fastcgi_param` to pass the parameter directly to PHP. - - location ~ [^/]\.php(/|$) { - … - include /etc/nginx/fastcgi_params; - fastcgi_param APP_NAME "VirtualHost Two"; - } - -> **Warning** Do not create a cache of your configuration (using `artisan config:cache`) if you have a multi-environnement setup. -> The cache is always having the priority on the variables set in the configuration files. - -#### Multiple .env option - -To do so, configure several web servers virtualhosts and set a specific `APP_ENV` environnement variable in each of them. - -Note that if `APP_ENV` is not set FlexiAPI will directly use the default `.env` file. - -FlexiAPI will then try to load a custom configuration file with the following name `.env.$APP_ENV`. So for the previous example `.env.foobar`. - -You can then configure your instances with specific values. - - INSTANCE_COPYRIGHT="FooBar - Since 1997" - INSTANCE_INTRO_REGISTRATION="Welcome on the FooBar Server" - INSTANCE_CUSTOM_THEME=true - … - -#### Custom theme - -If you set `INSTANCE_CUSTOM_THEME` to true, FlexiAPI will try to load a CSS file located in `public/css/$APP_ENV.style.css`. If the file doesn't exists it will fallback to `public/css/style.css`. - -You can find an example CSS file at `public/css/custom.style.css`. - -#### Flexisip Push notifications pusher - -The API endpoint `POST /account_creation_tokens/send-by-push` uses the `flexisip_pusher` binary delivered by the [Flexisip](https://gitlab.linphone.org/BC/public/flexisip) project (and related package). You must configure the `APP_FLEXISIP_PUSHER_PATH` and `APP_FLEXISIP_PUSHER_FIREBASE_KEYSMAP` environnement variables to point to the correct binary. - - APP_FLEXISIP_PUSHER_PATH=/opt/belledonne-communications/bin/flexisip_pusher - -This binary will be executed under "web user" privileges. Ensure that all the related files required by `flexisip_pusher` can be accessed using this user account. - - /var/opt/belledonne-communications/log/flexisip/flexisip-pusher.log // Write permissions - /etc/flexisip/apn/*pem // Read permissions - -### SELinux restrictions - -If you are running on a CentOS/RedHat machine, please ensure that SELinux is correctly configured. - -Allow the webserver user to write in the `storage/` directory: - - chcon -R -t httpd_sys_rw_content_t storage/ - -Don't forget to make this change persistent if the directory may be relabeled : - - semanage fcontext -a -t httpd_sys_rw_content_t storage/ - -You can use the restorecon command to verify that this is working : - - restorecon storage/ - -If your database is located on a remote machine, you should also allow your webserver user to connect to remote hosts: - - semanage port -a -t http_port_t -p tcp 3306 // Open remote connections on the MySQL port for example - setsebool -P httpd_can_network_connect 1 // Allow remote network connected - setsebool -P httpd_can_network_connect_db 1 // Allow remote database connection - -If you are planning to send emails using your account manager: - - setsebool -P httpd_can_sendmail 1 // Allow email to be sent +Check the `INSTALL.md` file. ## Usage @@ -152,7 +37,7 @@ FlexiAPI is shipped with several console commands that you can launch using the Create or update a Space, required to then create accounts afterward. The `super` option enable/disable the domain as a super domain. - php artisan spaces:create-update {domain} {--super} + php artisan spaces:create-update {sip_domain} {host} {--super} ### Create an admin account diff --git a/flexiapi/app/Http/Controllers/Account/DeviceController.php b/flexiapi/app/Http/Controllers/Account/DeviceController.php index 202d061..38ab6bb 100644 --- a/flexiapi/app/Http/Controllers/Account/DeviceController.php +++ b/flexiapi/app/Http/Controllers/Account/DeviceController.php @@ -21,13 +21,13 @@ namespace App\Http\Controllers\Account; use App\Http\Controllers\Controller; use Illuminate\Http\Request; -use App\Libraries\FlexisipConnector; +use App\Libraries\FlexisipRedisConnector; class DeviceController extends Controller { public function index(Request $request) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; return view( 'account.device.index', @@ -40,7 +40,7 @@ class DeviceController extends Controller public function delete(Request $request, string $uuid) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; return view( 'account.device.delete', @@ -54,7 +54,7 @@ class DeviceController extends Controller public function destroy(Request $request) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; $connector->deleteDevice($request->user()->identifier, $request->get('uuid')); return redirect()->route('account.device.index'); diff --git a/flexiapi/app/Http/Controllers/Admin/AccountDeviceController.php b/flexiapi/app/Http/Controllers/Admin/AccountDeviceController.php index 2952c3f..3e4a2a3 100644 --- a/flexiapi/app/Http/Controllers/Admin/AccountDeviceController.php +++ b/flexiapi/app/Http/Controllers/Admin/AccountDeviceController.php @@ -22,13 +22,13 @@ namespace App\Http\Controllers\Admin; use App\Account; use App\Http\Controllers\Controller; use Illuminate\Http\Request; -use App\Libraries\FlexisipConnector; +use App\Libraries\FlexisipRedisConnector; class AccountDeviceController extends Controller { public function index(int $accountId) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; $account = Account::findOrFail($accountId); return view( @@ -42,7 +42,7 @@ class AccountDeviceController extends Controller public function delete(int $accountId, string $uuid) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; $account = Account::findOrFail($accountId); return view( @@ -57,7 +57,7 @@ class AccountDeviceController extends Controller public function destroy(Request $request, int $accountId) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; $account = Account::findOrFail($accountId); $connector->deleteDevice($account->identifier, $request->get('uuid')); diff --git a/flexiapi/app/Http/Controllers/Api/Account/DeviceController.php b/flexiapi/app/Http/Controllers/Api/Account/DeviceController.php index e3d18ad..7123e63 100644 --- a/flexiapi/app/Http/Controllers/Api/Account/DeviceController.php +++ b/flexiapi/app/Http/Controllers/Api/Account/DeviceController.php @@ -20,7 +20,7 @@ namespace App\Http\Controllers\Api\Account; use App\Http\Controllers\Controller; -use App\Libraries\FlexisipConnector; +use App\Libraries\FlexisipRedisConnector; use Illuminate\Http\Request; use stdClass; @@ -28,14 +28,14 @@ class DeviceController extends Controller { public function index(Request $request) { - $devices = (new FlexisipConnector)->getDevices($request->user()->identifier); + $devices = (new FlexisipRedisConnector)->getDevices($request->user()->identifier); return ($devices->isEmpty()) ? new stdClass : $devices; } public function destroy(Request $request, string $uuid) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; return $connector->deleteDevice($request->user()->identifier, $uuid); } diff --git a/flexiapi/app/Http/Controllers/Api/Admin/DeviceController.php b/flexiapi/app/Http/Controllers/Api/Admin/DeviceController.php index 9a02eb5..f5ab7f1 100644 --- a/flexiapi/app/Http/Controllers/Api/Admin/DeviceController.php +++ b/flexiapi/app/Http/Controllers/Api/Admin/DeviceController.php @@ -20,7 +20,7 @@ namespace App\Http\Controllers\Api\Admin; use App\Http\Controllers\Controller; -use App\Libraries\FlexisipConnector; +use App\Libraries\FlexisipRedisConnector; use App\Account; use stdClass; @@ -28,14 +28,14 @@ class DeviceController extends Controller { public function index(int $accountId) { - $devices = (new FlexisipConnector)->getDevices(Account::findOrFail($accountId)->identifier); + $devices = (new FlexisipRedisConnector)->getDevices(Account::findOrFail($accountId)->identifier); return ($devices->isEmpty()) ? new stdClass : $devices; } public function destroy(int $accountId, string $uuid) { - $connector = new FlexisipConnector; + $connector = new FlexisipRedisConnector; return $connector->deleteDevice(Account::findOrFail($accountId)->identifier, $uuid); } diff --git a/flexiapi/app/Libraries/FlexisipPusherConnector.php b/flexiapi/app/Libraries/FlexisipPusherConnector.php index 47a1447..1e5f488 100644 --- a/flexiapi/app/Libraries/FlexisipPusherConnector.php +++ b/flexiapi/app/Libraries/FlexisipPusherConnector.php @@ -64,14 +64,14 @@ class FlexisipPusherConnector } } - public function sendToken(string $token) + public function sendToken(string $token): bool { $payload = json_encode(['token' => $token]); - $this->send(payload: $payload); + return $this->send(payload: $payload); } - public function send(?string $payload = null, ?string $callId = null, ?string $type = 'background') + public function send(?string $payload = null, ?string $callId = null, ?string $type = 'background'): bool { if (!empty($this->pusherPath)) { $command = $this->pusherPath @@ -96,11 +96,24 @@ class FlexisipPusherConnector } $output = null; - $retval = null; + $result = null; - return exec($command, $output, $retval); + exec($command . ' 2>&1', $output, $result); + + if ($result > 0) { + Log::error('Flexisip Pusher error', [ + 'command' => $command, + 'output' => $output + ]); + + return false; + } + + return true; } - Log::error('Pusher path not configured'); + Log::error('Flexisip Pusher path not configured'); + + return false; } } diff --git a/flexiapi/app/Libraries/FlexisipConnector.php b/flexiapi/app/Libraries/FlexisipRedisConnector.php similarity index 98% rename from flexiapi/app/Libraries/FlexisipConnector.php rename to flexiapi/app/Libraries/FlexisipRedisConnector.php index 7007d43..47e0d58 100644 --- a/flexiapi/app/Libraries/FlexisipConnector.php +++ b/flexiapi/app/Libraries/FlexisipRedisConnector.php @@ -24,7 +24,7 @@ use Illuminate\Support\Facades\Redis; use Illuminate\Support\Facades\Log; use stdClass; -class FlexisipConnector +class FlexisipRedisConnector { public function getDevices(string $from) { diff --git a/flexisip-account-manager.spec b/flexisip-account-manager.spec index f133880..d8bee04 100644 --- a/flexisip-account-manager.spec +++ b/flexisip-account-manager.spec @@ -49,6 +49,7 @@ cp -R flexiapi "$RPM_BUILD_ROOT%{opt_dir}" cp flexiapi/composer.json "$RPM_BUILD_ROOT%{opt_dir}/flexiapi" cp README* "$RPM_BUILD_ROOT%{opt_dir}/" +cp INSTALL* "$RPM_BUILD_ROOT%{opt_dir}/" mkdir -p $RPM_BUILD_ROOT/etc/cron.daily mkdir -p $RPM_BUILD_ROOT%{apache_conf_path} @@ -129,6 +130,7 @@ fi %files %{opt_dir}/flexiapi/ %{opt_dir}/README* +%{opt_dir}/INSTALL* %exclude %{opt_dir}/flexiapi/storage/ diff --git a/httpd/flexisip-account-manager.conf b/httpd/flexisip-account-manager.conf index 5f7ca53..05a0cb0 100644 --- a/httpd/flexisip-account-manager.conf +++ b/httpd/flexisip-account-manager.conf @@ -1,4 +1,4 @@ -Alias /flexiapi /opt/belledonne-communications/share/flexisip-account-manager/flexiapi/public +DocumentRoot /opt/belledonne-communications/share/flexisip-account-manager/flexiapi/public AllowOverride All @@ -27,8 +27,6 @@ Alias /flexiapi /opt/belledonne-communications/share/flexisip-account-manager/fl RewriteCond %{REQUEST_FILENAME} !-d RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^ index.php [L] - - RewriteBase /flexiapi/