Welcome to Roadmap, the open-source software for your roadmapping needs 🛣
- Completely customisable roadmapping software
- Mention users in comments
- Upvote items to see which has more priority
- Automatic slug generation
- Filament admin panel 💛
- Simplified role system (administrator, employee & user)
- OAuth 2 single sign-on with your own application
- Automatic OG image generation including branding color you've setup (saves in your storage, around 70kb per image), if title is too long it will strip automatically as well, example:
- PHP >= 8.2
- Database (MySQL, PostgreSQL)
- GD Library (>=2.0) or
- Imagick PHP extension (>=6.5.7)
- NodeJS (any version)
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.2-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?
- Administrator
- Obviously anything to users, items, projects, access admin
- Employee
- These can access the admin, and see their assigned items (via a filter). What they can't do: settings, theme, users, CRUD projects.
- User
- This is your default user when someone registers, they don't have access to the administration and can only access the frontend.
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 testPlease 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.