diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index ed57e0601f..b05024c4f2 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -6,18 +6,26 @@ - [How it works](getting-started/how-it-works.md) - [Quick start](getting-started/quick-start.md) -- [Install](getting-started/install.md) +- [Install](getting-started/install/README.md) + + - [On Express](getting-started/install/using-express.md) + - [On Koa](getting-started/install/using-koa.md) + - [On Fastify](getting-started/install/using-fastify.md) + - [On NestJS](getting-started/install/using-nest.md) + - [Troubleshooting](getting-started/install/troubleshooting.md) + - [Autocompletion & Typings](getting-started/autocompletion-and-typings.md) ## Data Sources - [Usage](datasources/README.md) - [Provided datasources](datasources/provided/README.md) - - [SQL (without ORM)](datasources/provided/sql.md) - [Sequelize](datasources/provided/sequelize.md) - [Mongoose](datasources/provided/mongoose.md) - +- [Multiple datasources](datasources/multiple-datasources/README.md) + - [Naming conflicts](datasources/multiple-datasources/naming-conflicts.md) + - [Relationships](datasources/multiple-datasources/relationships.md) - [Write your own](datasources/custom/README.md) - [Structure declaration](datasources/custom/structure.md) - [Using a local cache](datasources/custom/local-cache/README.md) diff --git a/docs/agent-customization/relationships/multiple-records.md b/docs/agent-customization/relationships/multiple-records.md index 409fc70914..3d2c986f76 100644 --- a/docs/agent-customization/relationships/multiple-records.md +++ b/docs/agent-customization/relationships/multiple-records.md @@ -14,8 +14,7 @@ agent.customizeCollection('countries', collection => collection.addOneToManyRelation('myTowns', 'towns', { originKey: 'country_id', originKeyTarget: 'id', // Optional (uses primary key of countries by default) - } - }), + }) ); ``` diff --git a/docs/assets/quickstart-editor-mode.png b/docs/assets/quickstart-editor-mode.png new file mode 100644 index 0000000000..e7d1db35ae Binary files /dev/null and b/docs/assets/quickstart-editor-mode.png differ diff --git a/docs/assets/quickstart-make-collection-visible.png b/docs/assets/quickstart-make-collection-visible.png new file mode 100644 index 0000000000..5f4fa50456 Binary files /dev/null and b/docs/assets/quickstart-make-collection-visible.png differ diff --git a/docs/assets/quickstart-no-collections.png b/docs/assets/quickstart-no-collections.png new file mode 100644 index 0000000000..a24ae8a14c Binary files /dev/null and b/docs/assets/quickstart-no-collections.png differ diff --git a/docs/datasources/README.md b/docs/datasources/README.md index 55ea81aaee..6d66aafdeb 100644 --- a/docs/datasources/README.md +++ b/docs/datasources/README.md @@ -19,7 +19,7 @@ Forest Admin collections map to any of those concepts: ## Example -In this example, we import a all tables from a PostgreSQL database into Forest Admin. +In this example, we import all tables from a PostgreSQL database into Forest Admin. Take note that data sources are defined in independent NPM packages (here `@forestadmin/datasource-sql`). @@ -31,58 +31,3 @@ const agent = createAgent(options).addDataSource( createSqlDataSource('postgres://user:pass@localhost:5432/mySchema'), ); ``` - -## Naming conflicts - -When importing collections to an admin panel, you may encounter naming collisions. - -You can tackle them by renaming the collection which are causing issues. - -Don't worry if you leave naming collisions, your development agent will warn you while starting. - -```javascript -const { createAgent } = require('@forestadmin/agent'); -const { createSqlDataSource } = require('@forestadmin/datasource-sql'); - -const agent = createAgent(options); -const sqlDataSource = new createSqlDataSource('postgres://user:pass@localhost:5432/mySchema'); - -// Rename sqlDataSource collections by providing replacements -agent.addDataSource(sqlDataSource, { - rename: { - customers: 'superCustomers', - }, -}); -``` - - diff --git a/docs/datasources/multiple-datasources/README.md b/docs/datasources/multiple-datasources/README.md new file mode 100644 index 0000000000..bef206ee05 --- /dev/null +++ b/docs/datasources/multiple-datasources/README.md @@ -0,0 +1,17 @@ +You can plug as many data sources as you want, no matter its type. +For example, you can plug a [Mongoose data source](../provided/mongoose.md) with a [SQL data source](../provided/sql.md). We take care of the compatibility for you. + +```javascript +const { createAgent } = require('@forestadmin/agent'); +const { createSqlDataSource } = require('@forestadmin/datasource-sql'); +const { createMongooseDataSource } = require('@forestadmin/datasource-mongoose'); +// Mongoose connection with its model declarations. +const connection = require('./mongoose-models'); + +// Instantiate data sources. +const sqlDataSource = createSqlDataSource('postgres://user:pass@localhost:5432/mySchema'); +const mongooseDataSource = createMongooseDataSource(connection); + +// Plug every created data sources to the agent. +const agent = createAgent(options).addDataSource(sqlDataSource).addDataSource(mongooseDataSource); +``` diff --git a/docs/datasources/multiple-datasources/naming-conflicts.md b/docs/datasources/multiple-datasources/naming-conflicts.md new file mode 100644 index 0000000000..7f700024e7 --- /dev/null +++ b/docs/datasources/multiple-datasources/naming-conflicts.md @@ -0,0 +1,23 @@ +When importing collections to an admin panel, you may encounter naming collisions. + +You can tackle them by renaming the collection that are causing issues. + +Don't worry if you leave naming collisions, your development agent will warn you while starting. + +```javascript +const { createAgent } = require('@forestadmin/agent'); +const { createSqlDataSource } = require('@forestadmin/datasource-sql'); + +const agent = createAgent(options); +const sqlDataSource = new createSqlDataSource('postgres://user:pass@localhost:5432/mySchema'); + +// Rename sqlDataSource collections by providing replacements +agent.addDataSource(sqlDataSource, { + // In this example, it will rename the `customers` and `stores` collections + // to `superCustomers` and `superStores`. + rename: { + customers: 'superCustomers', + stores: 'superStores', + }, +}); +``` diff --git a/docs/datasources/multiple-datasources/relationships.md b/docs/datasources/multiple-datasources/relationships.md new file mode 100644 index 0000000000..f4af9edeec --- /dev/null +++ b/docs/datasources/multiple-datasources/relationships.md @@ -0,0 +1,29 @@ +The relation mechanism allows you to add a relation between different data sources, regardless of their type. +It is a very powerful feature to link your different data sources. + +```javascript +const { createAgent } = require('@forestadmin/agent'); +const { createSqlDataSource } = require('@forestadmin/datasource-sql'); +const { createMongooseDataSource } = require('@forestadmin/datasource-mongoose'); + +// Mongoose connection with its model declarations. +const connection = require('./mongoose-models'); + +// Instanciate data sources. +const sqlDataSource = createSqlDataSource('postgres://user:pass@localhost:5432/mySchema'); +const mongooseDataSource = createMongooseDataSource(connection); + +// Plug every created data sources to the agent. +const agent = createAgent(options).addDataSource(sqlDataSource).addDataSource(mongooseDataSource); + +// Add a relation between a Mongoose collection and a SQL collection. +agent.customizeCollection('countryFromMongoose', collection => + collection.addOneToManyRelation('towns', 'townsFromSQL', { + originKey: 'country_id', + }), +); +``` + +{% hint style="info" %} +If you want to know more about adding relation, please refer to this [section](../custom/query-translation/relationships.md). +{% endhint %} diff --git a/docs/datasources/provided/mongoose.md b/docs/datasources/provided/mongoose.md index 36f6555bee..7fde98e203 100644 --- a/docs/datasources/provided/mongoose.md +++ b/docs/datasources/provided/mongoose.md @@ -1,5 +1,7 @@ The mongoose data source allows to import collections from a mongoose instance. +In order to make everything work as expected, you need to install the package `@forestadmin/datasource-mongoose@beta`. + {% tabs %} {% tab title="agent.js" %} ```javascript diff --git a/docs/datasources/provided/sequelize.md b/docs/datasources/provided/sequelize.md index 6f6abe26dd..0a79bfa9a3 100644 --- a/docs/datasources/provided/sequelize.md +++ b/docs/datasources/provided/sequelize.md @@ -1,5 +1,7 @@ The sequelize data source allows to import collections from a sequelize instance. +In order to make everything work as expected, you need to install the package `@forestadmin/datasource-sequelize@beta`. + Note that: - Sequelize scopes will be mapped to Forest Admin segments diff --git a/docs/datasources/provided/sql.md b/docs/datasources/provided/sql.md index 32b3f582db..d5f3871f0b 100644 --- a/docs/datasources/provided/sql.md +++ b/docs/datasources/provided/sql.md @@ -1,5 +1,9 @@ The SQL data source allows to import tables from SQL databases. +In order to make everything work as expected, you need to install the package `@forestadmin/datasource-sql@beta`. + +Depending on the database type you want to use, you may also need to install the associated javascript driver (`pg` for postgres, `mysql2` for mariadb/mysql, `tedious` for mssql, etc). + It supports the following vendors: - Postgres diff --git a/docs/getting-started/autocompletion-and-typings.md b/docs/getting-started/autocompletion-and-typings.md index 9facd1189f..53e12838f2 100644 --- a/docs/getting-started/autocompletion-and-typings.md +++ b/docs/getting-started/autocompletion-and-typings.md @@ -23,7 +23,7 @@ In a typescript context, usage of the typing file is pretty straightforward. You ```typescript import { createAgent } from '@forestadmin/agent'; -import Schema from './typings'; +import { Schema } from './typings'; import transactions from './customization/transactions'; createAgent({ diff --git a/docs/getting-started/how-it-works.md b/docs/getting-started/how-it-works.md index 1f3e26ac53..279ab1897a 100644 --- a/docs/getting-started/how-it-works.md +++ b/docs/getting-started/how-it-works.md @@ -5,7 +5,7 @@ Before you start writing a single line of code, it’s a good idea to get an ove Forest Admin provides you with: - An API hosted on your server to retrieve your data. We call it the **Agent**. It can be a **standalone project** or embedded **within your app**. -- A user interface to access and manage your data from your browser. This **Forest Admin User Interface** is built and managed through ressources hosted on Forest Admin's servers. +- A user interface to access and manage your data from your browser. This **Forest Admin User Interface** is built and managed through resources hosted on Forest Admin's servers. ![The agent is a Node.JS REST API hosted on your servers](../assets/how-it-work-architecture.png) diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md deleted file mode 100644 index dc22e8dac1..0000000000 --- a/docs/getting-started/install.md +++ /dev/null @@ -1,205 +0,0 @@ -Forest Admin is a low-code internal tool solution that scales with your project. With 30+ out-of-the-box tools and pre-built UI components, you can ship an admin panel in a few minutes, and then easily customise it to meet your specific business logic. Thanks to the layout editor, non-technical team members can adjust the UI to their needs. - -Forest Admin has a unique hybrid architecture - only the frontend is managed on Forest Admin servers, which gives you the flexibility of a SaaS tool without compromising on data security. - -## Requirements - -- A local or remote working database - -or - -- An existing javascript app, configured to work with a database - -Once you start creating a project, you will be able to choose a datasource. This page targets only the `SQL` datasource for now. - -If you have the choice, we strongly recommend integrating in an existing app as it is easier to maintain. - -The installation process will ask for your application endpoint. This endpoint must be correctly filled in order to onboard successfully. It is also required for the authentication process to work as expected. If you choose to make the agent independant of your main application, fill this endpoint with then endpoint you would like (http://localhost:3000 by default). - -## Install Forest Admin with an SQL database - -The following code example provide a way to run forestadmin as an independant process. - -In order to make everything work as expected, we strongly recommand to install the following packages via - -`yarn add @forestadmin/agent@beta @forestadmin/datasource-sql@beta dotenv` - -Depending on the database type you want to use, you may also need to install the associated javascript driver (`pg` for postgres, `mysql2` for mariadb/mysql, `tedious` for mssql, etc). - -For example, having an `index.js` containing: - -```javascript -require('dotenv').config(); - -// Import the requirements -const { createAgent } = require('@forestadmin/agent'); -const { createSqlDataSource } = require('@forestadmin/datasource-sql'); - -// Create your Forest Admin agent -(async () => { - await createAgent({ - authSecret: process.env.FOREST_AUTH_SECRET, - agentUrl: process.env.FOREST_AGENT_URL, - envSecret: process.env.FOREST_ENV_SECRET, - isProduction: process.env.NODE_ENV === 'production', - }) - .addDataSource(createSqlDataSource(process.env.DATABASE_URL)) - .mountOnStandaloneServer(3000) - .start(); -})(); -``` - -and a `.env` containing: - -```bash -FOREST_AUTH_SECRET= -FOREST_AGENT_URL= -FOREST_ENV_SECRET= -NODE_ENV=development -DATABASE_URL=your://development:database@connection.string -``` - -should be enough for you to fully onboard with the `SQL` datasource. - -## Install Forest Admin within an existing javascript app - -As you can see in the previous paragraph, Forest Admin is able to run in a completely isolated context. However, in order to easily maintain your agent, you may want to attach the it directly. - -### Example with `express` - -```javascript -require('dotenv').config(); - -// Import the requirements -const { createAgent } = require('@forestadmin/agent'); -const { createSqlDataSource } = require('@forestadmin/datasource-sql'); - -const express = require('express'); - -// Create your Forest Admin agent -(async () => { - const app = express(); - - app.listen(3000); - - await createAgent({ - authSecret: process.env.FOREST_AUTH_SECRET, - agentUrl: process.env.FOREST_AGENT_URL, - envSecret: process.env.FOREST_ENV_SECRET, - isProduction: process.env.NODE_ENV === 'production', - }) - .addDataSource(createSqlDataSource(process.env.DATABASE_URL)) - .mountOnExpress(app) - .start(); -})(); -``` - -### Example with `fastify` - -```javascript -require('dotenv').config(); - -// Import the requirements -const { createAgent } = require('@forestadmin/agent'); -const { createSqlDataSource } = require('@forestadmin/datasource-sql'); - -const { fastify } = require('fastify'); - -// Create your Forest Admin agent -(async () => { - const app = fastify(); - - app.listen(3000); - - await createAgent({ - authSecret: process.env.FOREST_AUTH_SECRET, - agentUrl: process.env.FOREST_AGENT_URL, - envSecret: process.env.FOREST_ENV_SECRET, - isProduction: process.env.NODE_ENV === 'production', - }) - .addDataSource(createSqlDataSource(process.env.DATABASE_URL)) - .mountOnFastify(app) - .start(); -})(); -``` - -### Example with `koa` - -```javascript -require('dotenv').config(); - -// Import the requirements -const { createAgent } = require('@forestadmin/agent'); -const { createSqlDataSource } = require('@forestadmin/datasource-sql'); - -const Koa = require('koa'); - -// Create your Forest Admin agent -(async () => { - const app = new Koa(); - - app.listen(3000); - - await createAgent({ - authSecret: process.env.FOREST_AUTH_SECRET, - agentUrl: process.env.FOREST_AGENT_URL, - envSecret: process.env.FOREST_ENV_SECRET, - isProduction: process.env.NODE_ENV === 'production', - }) - .addDataSource(createSqlDataSource(process.env.DATABASE_URL)) - .mountOnKoa(app) - .start(); -})(); -``` - -### Example with `NestJs` - -```javascript -require('dotenv').config(); - -// Import the requirements -import { createAgent } from '@forestadmin/agent'; -import { createSqlDataSource } from '@forestadmin/datasource-sql'; - -import { Module } from '@nestjs/common'; -import { NestFactory } from '@nestjs/core'; - -@Module({ imports: [], controllers: [], providers: [] }) -class AppModule {} - -// Create your Forest Admin agent -(async () => { - const app = await NestFactory.create(AppModule, { logger: false }); - - const agent = createAgent({ - authSecret: process.env.FOREST_AUTH_SECRET, - agentUrl: process.env.FOREST_AGENT_URL, - envSecret: process.env.FOREST_ENV_SECRET, - isProduction: process.env.NODE_ENV === 'production', - }) - .addDataSource(createSqlDataSource(process.env.DATABASE_URL)) - .mountOnNestJs(app); - - await app.listen(3000); - - await agent.start(); -})(); -``` - -## Help us get better! - -Finally, when your local server is started, you should be automatically redirected to a satisfaction form. Rate us so we can improve, then go to your newly created admin panel - -{% hint style="info" %} - -If you installed Forest Admin on a local environment, your admin backend will most likely run on an HTTP endpoint. - -This explains why, if you try to visit https://app.forestadmin.com, you will be redirected to http://app.forestadmin.com as this is the only way it can communicate with your local admin backend. - -Deploying your project to production will enforce HTTPS. - -{% endhint %} - -# Troubleshooting - -#### ❓ Don't you see an answer to your problem? Describe it on our [Developer Community Forum](https://community.forestadmin.com) and we will answer quickly. diff --git a/docs/getting-started/install/README.md b/docs/getting-started/install/README.md new file mode 100644 index 0000000000..9634799bd3 --- /dev/null +++ b/docs/getting-started/install/README.md @@ -0,0 +1,25 @@ +## Standalone vs In-app installation + +The Forest Admin agent can run as a Standalone server (You can see it in action in the [quickstart](../quick-start.md)), but can also be "attached" to an existing Node.js application server (That we usually call In-app). + +We recommend to install the Forest Admin agent "In-app" whenever it's possible, as our [Development and Deployment workflow](../../deployment/) can be tied to your application deployment process. + +However, if you don't already have an existing Node.js application, or if you prefer to run Forest Admin in an isolated context, you can still use our [Standalone](../quick-start.md) installation. + +{% hint style="info" %} + +The installation process will ask for your application endpoint. This endpoint must be correctly filled in order to onboard and to make the authentication process to work as expected. If you choose to make the agent run as Standalone process, fill this endpoint with then endpoint you would like your agent to run on (http://localhost:3000 by default). + +Also make sure that the port provided to `mountAsStandaloneServer` matches this endpoint. + +{% endhint %} + +## Requirements + +In order to install Forest Admin in a Javascript or Typescript environment, you'll need to install the `@forestadmin/agent@beta` package. It exposes all the code required to create a Forest Admin agent. + +You will also need to install at least one of [our data source](../../datasources/README.md) package. + +If you don't use it already, you can also install [dotenv](https://github.com/motdotla/dotenv), which ease the management of environment variables. Even though it is not mandatory for Forest Admin to run, the example provided in the following documentations will use it. + +The following sections will provide example to ease your installation process. All of them will show how to run the agent using an SQL data source on our supported application servers. diff --git a/docs/getting-started/install/troubleshooting.md b/docs/getting-started/install/troubleshooting.md new file mode 100644 index 0000000000..0b30c23341 --- /dev/null +++ b/docs/getting-started/install/troubleshooting.md @@ -0,0 +1,25 @@ +## Cross-Origin Resource Sharing (CORS) + +This is the most common issue you can encounter while setting up the Forest Admin Agent. +Opening the Developer Console of your browser will help to detect this kind of issue. As Forest Admin provide a complete middleware, please make sure: + +- That the Forest Admin Agent is mounted before any other middleware (Especially in a NestJS context, as the Nest App Factory allow to configure CORS on creation, and it can interfere with the `@forestadmin/agent@beta` package). +- That your server is up and running. This can be easily checked by using the `/forest` endpoint. + +## Help us get better! + +Finally, when your local server is started, you should be automatically redirected to a satisfaction form. Rate us so we can improve, then go to your newly created admin panel + +{% hint style="info" %} + +If you installed Forest Admin on a local environment, your admin backend will most likely run on an HTTP endpoint. + +This explains why, if you try to visit https://app.forestadmin.com, you will be redirected to http://app.forestadmin.com as this is the only way it can communicate with your local admin backend. + +Deploying your project to production will enforce HTTPS. + +{% endhint %} + +#### ❓ Don't you see an answer to your problem? + +Describe it on our [Developer Community Forum](https://community.forestadmin.com) and we will answer quickly. diff --git a/docs/getting-started/install/using-express.md b/docs/getting-started/install/using-express.md new file mode 100644 index 0000000000..48c0bef389 --- /dev/null +++ b/docs/getting-started/install/using-express.md @@ -0,0 +1,25 @@ +If you already have an application running using [Express](https://expressjs.com/), the easiest way to attach the Forest Admin agent would use the `mountOnExpress` function, just like in the following example: + +```javascript +require('dotenv').config(); + +const { createAgent } = require('@forestadmin/agent'); +const { createSqlDataSource } = require('@forestadmin/datasource-sql'); + +const express = require('express'); + +(async () => { + const app = express(); + + app.listen(3000); + + await createAgent({ + authSecret: process.env.FOREST_AUTH_SECRET, + agentUrl: process.env.FOREST_AGENT_URL, + envSecret: process.env.FOREST_ENV_SECRET, + isProduction: process.env.NODE_ENV === 'production', + }) + .mountOnExpress(app) + .start(); +})(); +``` diff --git a/docs/getting-started/install/using-fastify.md b/docs/getting-started/install/using-fastify.md new file mode 100644 index 0000000000..bbf52a67ab --- /dev/null +++ b/docs/getting-started/install/using-fastify.md @@ -0,0 +1,25 @@ +If you already have an application running using [Fastify](https://www.fastify.io/), the easiest way to attach the Forest Admin agent would use the `mountOnFastify` function, just like in the following example: + +```javascript +require('dotenv').config(); + +const { createAgent } = require('@forestadmin/agent'); +const { createSqlDataSource } = require('@forestadmin/datasource-sql'); + +const { fastify } = require('fastify'); + +(async () => { + const app = fastify(); + + app.listen(3000); + + await createAgent({ + authSecret: process.env.FOREST_AUTH_SECRET, + agentUrl: process.env.FOREST_AGENT_URL, + envSecret: process.env.FOREST_ENV_SECRET, + isProduction: process.env.NODE_ENV === 'production', + }) + .mountOnFastify(app) + .start(); +})(); +``` diff --git a/docs/getting-started/install/using-koa.md b/docs/getting-started/install/using-koa.md new file mode 100644 index 0000000000..6c688e939b --- /dev/null +++ b/docs/getting-started/install/using-koa.md @@ -0,0 +1,27 @@ +If you already have an application running using [Koa](https://koajs.com/), the easiest way to attach the Forest Admin agent would use the `mountOnKoa` function, just like in the following example: + +## Example with `koa` + +```javascript +require('dotenv').config(); + +const { createAgent } = require('@forestadmin/agent'); +const { createSqlDataSource } = require('@forestadmin/datasource-sql'); + +const Koa = require('koa'); + +(async () => { + const app = new Koa(); + + app.listen(3000); + + await createAgent({ + authSecret: process.env.FOREST_AUTH_SECRET, + agentUrl: process.env.FOREST_AGENT_URL, + envSecret: process.env.FOREST_ENV_SECRET, + isProduction: process.env.NODE_ENV === 'production', + }) + .mountOnKoa(app) + .start(); +})(); +``` diff --git a/docs/getting-started/install/using-nest.md b/docs/getting-started/install/using-nest.md new file mode 100644 index 0000000000..d2e55c4f73 --- /dev/null +++ b/docs/getting-started/install/using-nest.md @@ -0,0 +1,30 @@ +If you already have an application running using [NestJS](https://nestjs.com/), the easiest way to attach the Forest Admin agent would use the `mountOnNestJs` function, just like in the following example: + +```javascript +import 'dotenv/config'; + +import { createAgent } from '@forestadmin/agent'; +import { createSqlDataSource } from '@forestadmin/datasource-sql'; + +import { Module } from '@nestjs/common'; +import { NestFactory } from '@nestjs/core'; + +@Module({ imports: [], controllers: [], providers: [] }) +class AppModule {} + +(async () => { + const app = await NestFactory.create(AppModule, { logger: false }); + + const agent = createAgent({ + authSecret: process.env.FOREST_AUTH_SECRET, + agentUrl: process.env.FOREST_AGENT_URL, + envSecret: process.env.FOREST_ENV_SECRET, + isProduction: process.env.NODE_ENV === 'production', + }) + .mountOnNestJs(app); + + await app.listen(3000); + + await agent.start(); +})(); +``` diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index ea15abeffa..210f01a3e6 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -2,18 +2,152 @@ description: Let's get you up and running on Forest Admin in minutes! --- +# Introduction + +Forest Admin is a low-code internal tool solution that scales with your project. With 30+ out-of-the-box tools and pre-built UI components, you can ship an admin panel in a few minutes, and then easily customize it to meet your specific business logic. Thanks to the layout editor, non-technical team members can adjust the UI to their needs. + +Forest Admin has a unique hybrid architecture - only the frontend is managed on Forest Admin servers, which gives you the flexibility of a SaaS tool without compromising on data security. + # Quick Start +Forest Admin offers a lot of flexibility in terms of installation. The following guide provides a way to start using Forest Admin in minutes. If you want to dive deeper into the installation process of the product, we got you covered [here](./install/README.md). + +{% hint style='notice' %} + +This guide will help you to setup Forest Admin as a standalone process, using an example Postgres database. + +{% endhint %} + +## Requirements + +- Node.js ^14.15.0 || ^16.13.0 +- NPM > 6.14.4 or yarn > 1.22.17 +- If you want to use our example database, make sure Docker is installed and running + ## Create an account and follow the onboarding -Go to [https://app.forestadmin.com/signup](https://app.forestadmin.com/signup), and create an account and install your project. +Go to [https://app.forestadmin.com/signup](https://app.forestadmin.com/signup), and create an account and a new project. + +## Optionnal - Make sure you have a database running, or use our example -{% hint style="info" %} If you want to test Forest Admin but don't have a database on hand, here is one! `docker run -p 5432:5432 --name forest_demo_database forestadmin/meals-database` -{% endhint %} +The associated connection string will be `postgres://lumber:secret@localhost:5432/meals`. + +## Create a new JavaScript (Or TypeScript) project + +Let's create a new folder and init a new JavaScript project. + +```bash +mkdir ForestExample && cd ForestExample +yarn init +``` + +Once everything is ready, install the following dependencies. + +```bash +yarn add @forestadmin/agent@beta dotenv +``` + +Create an `index.js` and a `.env` file. + +{% tabs %} {% tab title="index.js" %} + +```javascript +require('dotenv').config(); + +// Import the requirements +const { createAgent } = require('@forestadmin/agent'); + +// Create your Forest Admin agent +createAgent({ + // These process.env variables should be provided in the onboarding + authSecret: process.env.FOREST_AUTH_SECRET, + agentUrl: process.env.FOREST_AGENT_URL, + envSecret: process.env.FOREST_ENV_SECRET, + isProduction: process.env.NODE_ENV === 'production', +}) + .mountOnStandaloneServer(3000) + .start(); +``` + +{% endtab %} {% tab title=".env" %} + +```bash +FOREST_AUTH_SECRET= +FOREST_AGENT_URL= +FOREST_ENV_SECRET= +NODE_ENV=development +``` + +{% endtab %} {% endtabs %} + +Running + +```bash +node index.js +``` + +should be enough to be redirected to the "rate-install" page. However, Forest Admin current don't have any collections to display. + +![](../assets/quickstart-no-collections.png) + +## Add a datasource + +Now that you are fully onboard, the only missing part is to add a data source. Forest Admin provide a way to [create your own](../datasources/custom/README.md), however for this example we will add an [SQL Datasource](../datasources/provided/sql.md). + +To install the SQL Data source package, you can run the following command + +```bash +yarn add @forestadmin/datasource-sql@beta +``` + +If you run on the example database provided above, simply add the following in your `index.js` and `.env` + +{% tabs %} {% tab title="index.js" %} + +```javascript +const { createSqlDataSource } = require('@forestadmin/datasource-sql'); + + //... + .addDataSource(createSqlDataSource(process.env.DATABASE_URL)) + .mountOnStandaloneServer(3000) + // ... +``` + +{% endtab %} {% tab title=".env" %} + +```bash +DATABASE_URL=postgres://lumber:secret@localhost:5432/meals +``` + +{% endtab %} {% endtabs %} + +If you try to run the code as is, you'll be prompted to install the `pg` driver manually. +After doing: + +```bash +yarn add pg +node index.js +``` + +You should be able to see the following log in your terminal: + +``` +info: Schema was updated, sending new version +``` + +And refreshing the Forest Admin app should display the following screen: + +![](../assets/quickstart-editor-mode.png) + +Click on the "eyes" icons of the collections you want to display, then exit the layout editor and ... + +![](../assets/quickstart-make-collection-visible.png) + +You're all set! At the end of your onboarding, you will **out-of-the-box** be able to: @@ -25,14 +159,3 @@ At the end of your onboarding, you will **out-of-the-box** be able to: - Search and filter **(6)** ![](../assets/quick-start-abilities.png) - -## Prerequisites - -- Node.js ^14.15.0 || ^16.13.0 -- NPM > 6.14.4 or yarn > 1.22.17 - -If you meet those prerequisites, we strongly recommand to follow our [Install guide](./install.md) - -## Troubleshooting - -If you encounter any issue while installing the Forest Admin agent, join our [community](https://community.forestadmin.com/).