Stars: 300
Forks: 64
Pull Requests: 136
Issues: 102
Watchers: 10
Last Updated: 2023-09-04 12:55:38
Open source roadmapping software
License: MIT License
Languages: PHP, JavaScript, Blade, CSS, Dockerfile
Welcome to Roadmap, the open-source software for your roadmapping needs 🛣
First set up a database, and remember the credentials.
git clone https://github.com/ploi/roadmap.git
composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
php -r "file_exists('.env') || copy('.env.example', '.env');"
php artisan key:generate
Now edit your .env
file and set up the database credentials, including the app name you want.
Optionally you may set up the language with APP_LOCALE
, if your language is not working we accept PR's for new languages. We recommend copying those files from the lang/en
folder.
As well as the timezone can be set with APP_TIMEZONE
, for example: APP_TIMEZONE="Europe/Amsterdam"
.
Now run the following:
php artisan roadmap:install
And login with the credentials you've provided, the user you've created will automatically be admin.
To manage your servers and sites, we recommend using Ploi.io to speed up things, obviously you're free to choose however you'd like to deploy this piece of software 💙
That being said, here's an deployment script example:
cd /home/ploi/example.com
git pull origin main
composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
echo "" | sudo -S service php8.1-fpm reload
php artisan route:cache
php artisan view:clear
php artisan migrate --force
npm ci
npm run production
echo "🚀 Application deployed!"
Alternatively you can also use the upgrade command to clean up your deployment script:
cd /home/ploi/example.com
git pull origin main
composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
echo "" | sudo -S service php8.1-fpm reload
php artisan roadmap:upgrade
npm ci
npm run production
echo "🚀 Application deployed!"
If you're using queue workers (which we recommend to do) also add php artisan queue:restart
to your deployment script.
There's a simplified role system included in this roadmapping software. There's 3 roles: administrator, employee & user.
What are these roles allowed to do?
To enable the GitHub integration, add these values to your .env:
GITHUB_ENABLED=true
GITHUB_TOKEN=your_github_token
To get a GitHub token, visit this URL: https://github.com/settings/tokens
When enabled, you can assign a repository to each project via the admin panel. For items in projects with a repo assigned, you'll be able to assign an issue or easily create one via the roadmap admin.
It is possible to configure OAuth 2 login with this roadmap software to make it easier to log in. In this example we're going to show how to set this up with a Laravel application example, but any other OAuth 2 capable application should be able to integrate as well.
Start by installing Laravel Passport into your application, consult their docs how to do this.
Now create a fresh client by running php artisan passport:client
It will ask you a few questions, an example how to answer these:
$ php artisan passport:client
Which user ID should the client be assigned to?:
>
What should we name the client?:
> Roadmap SSO
Where should we redirect the request after authorization? [https://my-app.com/oauth/callback]:
>
New client created successfully.
Client ID: 3
Client secret: 9Mqb2ssCDwk0BBiRwyRZPVupzkdphgfuBgEsgpjQ
Enter these credentials inside your .env file of the roadmap:
SSO_LOGIN_TITLE="Login with SSO"
SSO_BASE_URL=https://external-app.com
SSO_CLIENT_ID=3
SSO_CLIENT_SECRET=9Mqb2ssCDwk0BBiRwyRZPVupzkdphgfuBgEsgpjQ
SSO_CALLBACK=${APP_URL}/oauth/callback
# Mostly, your sso provider user endpoint response is wrapped in a `data` key.
# for example: { "data": "id": "name": "John Doe", "email": "[email protected]" }
# If you would like to use a custom key instead of data, you may define it here.
# you can also do something like 'data.user' if its nested.
# or you can set it to nothing (do not set it to value 'null'. just leave it empty value)
# if sso provider user endpoint response is not wrapped in a key.
SSO_PROVIDER_USER_ENDPOINT_DATA_WRAP_KEY="data"
# The keys that should be present in the sso provider user endpoint response
SSO_PROVIDER_USER_ENDPOINT_KEYS="id,email,name"
# The provider id returned by the sso provider for the user identification. sometimes its `uuid` instead of `id`
SSO_PROVIDER_ID="id"
SSO_ENDPOINT_AUTHORIZE=${SSO_BASE_URL}/oauth/authorize
SSO_ENDPOINT_TOKEN=${SSO_BASE_URL}/oauth/token
SSO_ENDPOINT_USER=${SSO_BASE_URL}/oauth/user
Next we're going to prepare the routes, controller & resource for your application.
Create these routes inside the api.php
file:
Route::get('oauth/user', [Api\UserOAuthController::class, 'user'])->middleware('scopes:email');
Route::delete('oauth/revoke', [Api\UserOAuthController::class, 'revoke']);
Create the resource: php artisan make:resource Api/UserOAuthResource
with the following contents in the toArray()
method:
public function toArray($request)
{
return [
'id' => $this->id,
'name' => $this->name,
'email' => $this->email,
];
}
Create a controller php artisan make:controller Api/UserOAuthController
and add these functions:
use App\Http\Resources\Api\UserOAuthResource;
use Laravel\Passport\RefreshTokenRepository;
use Laravel\Passport\TokenRepository;
public function user(Request $request)
{
return new UserOAuthResource($request->user());
}
public function revoke(Request $request)
{
$token = $request->user()->token();
$tokenRepository = app(TokenRepository::class);
$refreshTokenRepository = app(RefreshTokenRepository::class);
$tokenRepository->revokeAccessToken($token->id);
$refreshTokenRepository->revokeRefreshTokensByAccessTokenId($token->id);
}
Also setup the tokens inside the AppServiceProvider
inside the boot()
method:
public function boot()
{
...
Passport::tokensCan([
'email' => 'Read email'
]);
}
Now head over to the login page in your roadmap software and view the log in button in action. The title of the button can be set with the .env
variable: SSO_LOGIN_TITLE=
Go into docker folder and run:
docker-compose up -d --build
Set your database .env variables:
DB_CONNECTION=mysql
DB_HOST=roadmap-db
DB_PORT=3306
DB_DATABASE=roadmap
DB_USERNAME=root
DB_PASSWORD=secret
Composer Install:
docker exec -it roadmap composer install --no-interaction --prefer-dist --optimize-autoloader --no-dev
NPM Install:
docker exec -it roadmap npm ci
Running artisan commands:
docker exec -it roadmap php artisan <command>
The Application will be running on localhost:1337
and PhpMyAdmin is running on localhost:8010
There are a few heroicons that were giving issues when running locally with docker.
Unable to locate a class or view for component <insert heroicon name here>
The problem was resolved by simply changing the following icons:
x-heroicon-o-chevron-down -> x-heroicon-s-chevron-down (group.blade.php) heroicon-o-chat -> heroicon-s-chat (CommentResource) heroicon-o-archive -> heroicon-s-archive (ItemResource) heroicon-o-x-circle -> heroicon-o-collection (notifications.blade.php)
Related Issues:
laravel-filament/filament#2677
blade-ui-kit/blade-heroicons#9
composer test
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
We appreciate sponsors, we still maintain this repository, server, emails and domain. You can do that here. Each sponsor gets listed on in this readme.
Obviously, if you do not want to self host, there's plenty of self-hosted solutions, a small rundown:
The MIT License (MIT). Please see License File for more information.