Skip to content

Commit 71fc037

Browse files
MaikMichelMaikMichel
committed
Modified documentation concerning setup
1 parent 09f8fdb commit 71fc037

File tree

3 files changed

+149
-110
lines changed

3 files changed

+149
-110
lines changed

‎docs/getting_started.md

Lines changed: 0 additions & 107 deletions
This file was deleted.

‎docs/setup.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Getting startet
2+
3+
## Requirements
4+
5+
To use **dbFlow**, all you need is:
6+
7+
* [Git]
8+
* [SQLPlus inkl. Oracle Client] or [SQLcl]
9+
* bash
10+
- on Windows included as git-bash
11+
- on MacOS included as bash (old) or zsh (unstable)
12+
- on Linux it just should work
13+
14+
[Git]: https://git-scm.com/downloads
15+
[SQLPlus inkl. Oracle Client]: https://www.oracle.com/database/technologies/instant-client/downloads.html
16+
[SQLcl]: https://www.oracle.com/de/tools/downloads/sqlcl-downloads.html
17+
18+
19+
## Installation
20+
21+
Basically, installing **dbFLow** consists of nothing more than initializing a directory with git and then cloning the repository as a submodule from GitHub. If you are using an existing git directory / project, cloning the submodule is all you need to do.
22+
23+
> The cloning of **dbFlow** as a submodule has the advantage that you can source new features and bugfixes directly from Github. In addition, you always have the possibility to fall back on an older **dbFLow** version through branching.
24+
25+
!!! warning "Important!"
26+
27+
dbFlow **MUST** exist as a folder named ".dbFlow"
28+
29+
### Starting a new Project
30+
31+
```bash
32+
# create a folder for your project and change directory into
33+
$ mkdir demo && cd demo
34+
35+
# init your project with git
36+
$ git init
37+
38+
# clone dbFlow as submodule
39+
$ git submodule add https://github.com/MaikMichel/dbFlow.git .dbFlow
40+
41+
```
42+
43+
44+
### Initialize an existing Project
45+
46+
```bash
47+
# change into your project directory
48+
$ cd demo
49+
50+
# clone dbFlow as submodule
51+
$ git submodule add https://github.com/MaikMichel/dbFlow.git .dbFlow
52+
53+
```
54+
55+
> Sometimes it can happen that the bash files cannot be executed. If this is the case, explicit permissions must be granted here. (`chmod +x .dbFlow/*.sh`)
56+
57+
58+
## Setting up a project
59+
60+
To configure a **dbFlow** project, set it up initially with the command `.dbFlow/setup.sh --generate <project_name>`. After that some informations about the project are expected. All entries are stored in the two files `build.env` and `apply.env`. `build.env` contains information about the project itself and `apply.env` contains information about the database connection and environment. The filename `apply.env` is stored in the file `.gitignore` and should not be versioned. Since this file contains environment related information, it is also exactly the one that changes per instance / environment. All settings in this file can be entered also from "outside", in order to fill these for example from a CI/CD Tool.
61+
62+
!!! info
63+
64+
You can always execute a bash script/command inside `.dbFLow` folder without arguments to show usage help.
65+
66+
### Generate Project
67+
68+
```bash
69+
$ .dbFlow/setup.sh --generate <project_name>
70+
```
71+
72+
You will be asked the following questions when creating the project:
73+
74+
75+
| Question | Notes |
76+
|----------|-------|
77+
| Which **dbFLow** project type do you want to create? **==S==**ingle, **==M==**ulti or **==F==**lex [M] | This is the first question. Here you define the project mode. Default is **==M==**ulti . ( see: [project-types]) |
78+
| When running release tests, what is your prefered branch name [build] | Later you have the possibility to run so called release tests (NightlyBuilds) . Here you determine the branch name for the tests. The default here is **build**. |
79+
| Would you like to process changelogs during deployment [Y] | **dbFlow** offers the possibility to generate changlogs based on the commit messages. Here you activate this function. ( see: [changelog]) |
80+
| What is the schema the changelog is processed with [schema_name] | If you want changelogs to be displayed within your application, you can specify the target schema here, with which the corresponding TemplateCode should be executed. ( see: [changelog]) |
81+
| Enter database connections [localhost:1521/xepdb1] | Place your connection string like: host:port/service |
82+
| Enter username of admin user (admin, sys, ...) [sys] | This user is responsible for all scripts inside `db/_setup` folder |
83+
| Enter password for sys [leave blank and you will be asked for] | Nothing more to clarify. Password is written to apply.env which is mentioned in .gitignore. (Keep in mind that passwords are saved obfuscated) |
84+
| Enter password for deployment_user (proxyuser: ?_depl) [leave blank and you will be asked for] | Nothing more to clarify. Password is written to apply.env which is mentioned in .gitignore. (Keep in mind that passwords are saved obfuscated) |
85+
| Enter path to depot [_depot] | This is a relative path which points to the depot (artifactory) and is also mentioned in .gitignore (see: [depot])|
86+
| Enter stage of this configuration mapped to branch (develop, test, master) [develop] | When importing the deployment, this setting assigns the database connection to the source branch |
87+
| Do you wish to generate and install default tooling? (Logger, utPLSQL, teplsql, tapi) [Y] | Here you activate the initial installation of the different components/dependencies. These are placed in the `db/_setup/features` folder. There you can also place other features by yourself. If you don't need certain components, you can delete the corresponding file from the features folder (before running the actual installation)..
88+
| Install with sql(cl) or sqlplus? [sqlplus] | Here you define which CLI **dbFLow** should use to execute the SQL scripts. |
89+
| Enter application IDs (comma separated) you wish to use initialy (100,101,...) | Here you can already enter the application IDs that **dbFlow** should initially take care of |
90+
| Enter restful Moduls (comma separated) you wish to use initialy (api,test,...) | Here you can already specify the REST modules that **dbFlow** should initially take care of |
91+
92+
93+
[changelog]: ../changelog/#configuration
94+
[project-types]: ../concept/#project-types
95+
[depot]: ../concept/#depot
96+
97+
After answering all the questions, your project structure is created with some SQL and bash files inside. You can now modifiy these files and / or put some files of your own into the corresponding folders.
98+
99+
#### Without wizard
100+
101+
Sometimes you want to have this questions and answers filled directly from the environment. In this case it is enough to specify the --wizard flag.
102+
103+
```bash
104+
$ .dbFlow/setup.sh --generate <project_name> --wizard
105+
```
106+
107+
This is especially useful if you want to build such a project scripted via a CI/CD.
108+
109+
#### Just environment
110+
111+
This is especially important for instance directories. So if you assign a directory to a target stage, you can install the actual patch from depot and get the complete directory structure written to the current directory via this.
112+
113+
```bash
114+
$ .dbFlow/setup.sh --generate <project_name> --envonly
115+
```
116+
117+
### Copy Project
118+
119+
As an addition to the generation of a project with the `--envonly` option, one has the possibility to copy the configuration and the setup, so the foundation, into a new target directory.
120+
121+
```bash
122+
$ .dbFlow/setup.sh --copyto <target-path>
123+
```
124+
125+
This is useful when you want to make your target instance project ready. So after customizing the data connection in the `apply.env` in the target directory you can install all dependencies like schemas, features and workspaces in the target instance.
126+
127+
### Install Project
128+
129+
> When you fullfilled the steps in the previous section, you are ready to install the project with dependencies into your database
130+
131+
```bash
132+
$ .dbFlow/setup.sh --install
133+
```
134+
> This will run all SQL and bash files inside the db/_setup directory.
135+
136+
For deployment or release purposes. This is the time to make all branches equal. So if you are on master and this your only branch, create a branch for each
137+
deployment stage (develop, test, ...) or if you allready did that, just merge these changes into your branches.
138+
139+
!!! warning "Important!"
140+
141+
The installation will abort if the users already exist in the DB as a schema. Furthermore, during the installation of the standard features, it will ask in each case, if they already exist, whether they should be overwritten.
142+
You have the option to flag this with a step *force* by using `.dbFlow/setup.sh --install --force`. In this case, all target schemas and features are deleted before the actual installation in each case.
143+
144+
145+
146+
147+
[How to make a release]: ../release

‎mkdocs.yml

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
site_name: dbFLow - Documentation
22
nav:
3-
- Home: index.md
43
- Start: start.md
5-
- The Concept: concept.md
6-
- How to setup: getting_started.md
4+
- Concept: concept.md
5+
- Setup: setup.md
76
- How to deploy: deployment.md
87
- Generating a changelog: changelog.md
98
- Migrating from previous: migrating.md

0 commit comments

Comments
 (0)