You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: adminforth/commands/createApp/templates/readme.md.hbs
+13-2Lines changed: 13 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ Install dependencies:
7
7
```
8
8
9
9
{{#ifadminUserTableInstructions}}
10
-
Prepare the admin users table in your existing database before starting the app. AdminForth uses this table for back-office authentication, and your own migration tool should own this schema change. The schema below is only an example:
10
+
Create the admin users table in your database before starting the app: AdminForth needs it for back-office authentication, and no Prisma migrations were generated for this project.
11
11
12
12
{{{adminUserTableInstructions}}}
13
13
@@ -23,6 +23,13 @@ Create the initial migration and apply it to the database:
23
23
```
24
24
{{/if}}
25
25
26
+
First-time setup on a fresh clone: `create-app` wrote a random `ADMINFORTH_SECRET` into `.env`, but that file is gitignored, so every developer and every deployment creates their own (see `.env.example`). The command below only creates `.env` when it does not exist yet:
27
+
28
+
```bash
29
+
# On Windows (PowerShell): node -e "require('fs').writeFileSync('.env', 'ADMINFORTH_SECRET=' + require('crypto').randomBytes(32).toString('hex') + '\n', { flag: 'wx' })"
When you provide your own database URL, the CLI treats this as your own database. It does not create Prisma schema or Prisma migration scripts for that database. Instead, the generated project README contains the SQL or schema notes for adding the required `adminuser` table with your own migration tool.
37
+
The CLI connects to the database and checks whether it already contains tables — passing `--db` alone does not decide the path. If tables exist, the database is treated as your own: no Prisma schema or migration scripts are generated, and both the CLI output and the generated project README contain the SQL for adding the required `adminuser` table with your own migration tool (MongoDB needs no table up front — the collection is created on first write). If a PostgreSQL, MySQL or SQLite database is still empty, the CLI asks `Include Prisma migrations? >` — answer **No** to keep managing the schema yourself and you get the same `adminuser` SQL; answer **Yes** and AdminForth manages the schema for you (see Path 2). The CLI offers Prisma migrations only for PostgreSQL, MySQL and SQLite, so MongoDB and ClickHouse never get the question and always keep their schema yours. If the CLI cannot load the database connector (for example offline, or the installed connector is too old to inspect a database), it warns, continues as if the database were empty and defaults the question to **No**, so pressing Enter never scaffolds migrations over a database that may already hold data; a database it cannot connect to makes `create-app` fail with the connection error.
38
38
39
39
After the project is created, navigate into it and generate resources from your existing tables:
40
40
@@ -65,12 +65,12 @@ Once the project is created, navigate into its directory:
65
65
cd myadmin # or any other name you provided
66
66
```
67
67
68
-
For the new database path, the CLI can scaffold Prisma files and migration scriptsfor the default SQLite database.
68
+
For an empty database (the default SQLite file, or an empty SQLite/PostgreSQL/MySQL database passed with `--db`), the CLI asks `Include Prisma migrations? >`, defaulting to **Yes**. Answer **Yes** to have AdminForth scaffold the Prisma schema and migration scripts; answer **No** to manage the schema yourself — the CLI output and the generated README then contain the SQL for the required `adminuser` table.
69
69
70
70
CLI options:
71
71
72
72
***`--app-name`** - name for your project. Used in `package.json`, `index.ts` branding, etc. Default value: **`adminforth-app`**.
73
-
***`--db`** - database connection string. Currently PostgreSQL, MongoDB, SQLite, MySQL, Clickhouse and Qdrant (read only) are supported. Default value: **`sqlite://.db.sqlite`**
│ └── tsconfig.json # Tsconfig for Vue project (adds completion for AdminForth core components)
96
96
├── resources
97
97
│ └── adminuser.ts # Example resource file for users management
98
-
├── schema.prisma # Prisma schema file, generated only for the new database path
98
+
├── schema.prisma # Prisma schema file, generated only when you include Prisma migrations
99
99
├── index.ts # Main entry point: configures AdminForth & starts the server
100
100
├── package.json # Project dependencies
101
101
├── pnpm-workspace.yaml
102
102
├── tsconfig.json # TypeScript configuration
103
-
├── .env # Env vars like tokens, secrets that should not be in version control
103
+
├── .env # Env vars like tokens, secrets that should not be in version control (ADMINFORTH_SECRET is generated here for you)
104
+
├── .env.example # Committed template listing the secrets each developer must create locally
104
105
├── .env.local # General local environment variables
105
106
└── .gitignore
106
107
107
108
```
108
109
109
110
### Initial Migration & Future Migrations
110
111
111
-
For the new database path, the CLI creates Prisma files for managing migrations. Prisma is not required by AdminForth itself, but it is a convenient migration tool for standalone projects that do not have database management yet.
112
+
When you answer **Yes** to `Include Prisma migrations? >`, the CLI creates Prisma files for managing migrations. Prisma is not required by AdminForth itself, but it is a convenient migration tool for standalone projects that do not have database management yet.
112
113
113
114
CLI will suggest you a command to initialize the database with Prisma:
Other developers need to pull migration and run `pnpm migrate:local` to apply any unapplied migrations.
128
129
129
-
For the existing database path, use your own migration tool instead. The generated project README shows how to add the required `adminuser` table to your database.
130
+
When no Prisma migrations were generated — the database already had tables, you answered **No**, or the database is MongoDB or ClickHouse — use your own migration tool instead. The CLI output and the generated project README show how to add the required `adminuser` table to your database (MongoDB needs none).
Copy file name to clipboardExpand all lines: adminforth/documentation/docs/tutorial/01-helloWorld.md
+13-1Lines changed: 13 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,12 +47,24 @@ Create two files in your project's root directory:
47
47
Put the following content to the `.env.local` file:
48
48
49
49
```bash title="./.env.local"
50
-
ADMINFORTH_SECRET=123
51
50
NODE_ENV=development
52
51
DATABASE_URL=sqlite://.db.sqlite
53
52
PRISMA_DATABASE_URL=file:.db.sqlite
54
53
```
55
54
55
+
Generate a signing key into the gitignored `.env` file, readable by you only (AdminForth logs a warning at startup if the secret is shorter than 16 characters; on Windows without openssl use `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`):
0 commit comments