github.com/ddev/ddev@v1.23.2-0.20240519125000-d824ffe36ff3/docs/content/users/usage/managing-projects.md (about)

     1  ## Configuration Files
     2  
     3  The [`ddev config`](../usage/commands.md#config) and `ddev start` commands attempt to create a CMS-specific settings file pre-populated with DDEV credentials. If you don't want DDEV to do this, set the [`disable_settings_management`](../configuration/config.md#disable_settings_management) config option to `true`.
     4  
     5  For **Craft CMS** DDEV settings are added to the `.env` file.
     6  
     7  For **Django 4** DDEV settings are placed in `.ddev/settings/settings.django4.py` and a stanza is added to your `settings.py` that is only invoked in DDEV context.
     8  
     9  For **Drupal** and **Backdrop**, DDEV settings are written to a DDEV-managed file, `settings.ddev.php`. The `ddev config` command will ensure these settings are included in your `settings.php` through the following steps:
    10  
    11  - Write DDEV settings to `settings.ddev.php`.
    12  - If no `settings.php` file exists, create one that includes `settings.ddev.php`.
    13  - If a `settings.php` file already exists, ensure that it includes `settings.ddev.php`, modifying `settings.php` to write the include if necessary.
    14  
    15  For **Magento 1**, DDEV settings go into `app/etc/local.xml`.
    16  
    17  In **Magento 2**, DDEV settings go into `app/etc/env.php`.
    18  
    19  For **TYPO3**, DDEV settings are written to `AdditionalConfiguration.php`. If `AdditionalConfiguration.php` exists and is not managed by DDEV, it will not be modified.
    20  
    21  For **WordPress**, DDEV settings are written to a DDEV-managed file, `wp-config-ddev.php`. The `ddev config` command will attempt to write settings through the following steps:
    22  
    23  - Write DDEV settings to `wp-config-ddev.php`.
    24  - If no `wp-config.php` exists, create one that include `wp-config-ddev.php`.
    25  - If a DDEV-managed `wp-config.php` exists, create one that includes `wp-config.php`.
    26  - If a user-managed `wp-config.php` exists, instruct the user on how to modify it to include DDEV settings.
    27  
    28  You’ll know DDEV is managing a settings file when you see a comment containing `#ddev-generated` like the one below. Remove the comment and DDEV will not attempt to overwrite it. If you’re letting DDEV create its settings file, we recommended leaving this comment so DDEV can continue to manage it, and make any needed changes in another settings file.
    29  
    30  ```
    31  /**
    32   #ddev-generated: Automatically generated Drupal settings.php file.
    33   ddev manages this file and may delete or overwrite the file unless this comment is removed.
    34   */
    35  ```
    36  
    37  If you’re providing the `settings.php` or `wp-config.php` and DDEV is creating `settings.ddev.php` (or `wp-config-local.php`, `AdditionalConfig.php`, or similar), the main settings file must explicitly include the appropriate DDEV-generated settings file. Any changes you need should be included somewhere that loads after DDEV’s settings file, for example in Drupal’s `settings.php` _after_ `settings.ddev.php` is included. (See [Adding Configuration](#adding-configuration) below).
    38  
    39  ### Adding Configuration
    40  
    41  **Drupal and Backdrop**: In `settings.php`, enable loading `settings.local.php` after `settings.ddev.php` is included—creating a new one if it doesn’t already exist—and make changes there. Wrap with `if (getenv('IS_DDEV_PROJECT') == 'true')` as needed.
    42  
    43  **WordPress**: Load a `wp-config-local.php` after `wp-config-ddev.php`, and make changes there. Wrap with `if (getenv('IS_DDEV_PROJECT') == 'true')` as needed.
    44  
    45  ## Listing Project Information
    46  
    47  Run [`ddev list`](../usage/commands.md#list) or `ddev list --active-only` current projects.
    48  
    49  ```
    50  ➜  ddev list
    51   NAME            STATUS        LOCATION                    URL                           TYPE
    52   bakerydemo      running (ok)  ~/workspace/bakerydemo      https://bakerydemo.ddev.site  django4
    53   d10             stopped       ~/workspace/d10                                           drupal10
    54   drup            running (ok)  ~/workspace/drup            https://drup.ddev.site        drupal
    55   my-cakephp-app  stopped       ~/workspace/my-cakephp-app                                cakephp
    56   Router          healthy       ~/.ddev                     http://127.0.0.1:10999        traefik
    57  ```
    58  
    59  ```
    60  
    61  ➜  ddev list --active-only
    62   NAME        STATUS        LOCATION                URL                           TYPE
    63   bakerydemo  running (ok)  ~/workspace/bakerydemo  https://bakerydemo.ddev.site  django4
    64   drup        running (ok)  ~/workspace/drup        https://drup.ddev.site        drupal
    65   Router      healthy       ~/.ddev                 http://127.0.0.1:10999        traefik
    66  ```
    67  
    68  You can also see more detailed information about a project by running [`ddev describe`](../usage/commands.md#describe) from its working directory. You can also run `ddev describe [project-name]` from any location to see the detailed information for a running project.
    69  
    70  ```
    71  $ ddev describe drup
    72  ┌──────────────────────────────────────────────────────────────────────────────────┐
    73  │ Project: drup ~/workspace/drup https://drup.ddev.site                            │
    74  │ Docker platform: orbstack                                                        │
    75  │ Router: traefik                                                                  │
    76  ├──────────┬──────┬───────────────────────────────────────────┬────────────────────┤
    77  │ SERVICE  │ STAT │ URL/PORT                                  │ INFO               │
    78  ├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
    79  │ web      │ OK   │ https://drup.ddev.site                    │ drupal PHP8.3      │
    80  │          │      │ InDocker: web:8025,443,80                 │ nginx-fpm          │
    81  │          │      │ Host: 127.0.0.1:33016,33017               │ docroot:'web'      │
    82  │          │      │                                           │ Perf mode: mutagen │
    83  │          │      │                                           │ NodeJS:20          │
    84  ├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
    85  │ db       │ OK   │ InDocker: db:3306                         │ mariadb:10.11      │
    86  │          │      │ Host: 127.0.0.1:33018                     │ User/Pass: 'db/db' │
    87  │          │      │                                           │ or 'root/root'     │
    88  ├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
    89  │ Mailpit  │      │ Mailpit: https://drup.ddev.site:8026      │                    │
    90  │          │      │ `ddev mailpit`                            │                    │
    91  ├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
    92  │ All URLs │      │ https://drup.ddev.site,                   │                    │
    93  │          │      │ https://127.0.0.1:33016,                  │                    │
    94  │          │      │ http://drup.ddev.site,                    │                    │
    95  │          │      │ http://127.0.0.1:33017                    │                    │
    96  └──────────┴──────┴───────────────────────────────────────────┴────────────────────┘
    97  ```
    98  
    99  ## Removing Projects
   100  
   101  There are two ways to remove a project from DDEV’s listing.
   102  
   103  The first, the [`ddev delete`](../usage/commands.md#delete) command, is destructive. It removes the project from DDEV’s list, deletes its database, and removes the hostname entry from the hosts file:
   104  
   105  `ddev delete <projectname>`
   106  or
   107  `ddev delete --omit-snapshot <projectname>`
   108  
   109  If you don’t want the project to show up in [`ddev list`](../usage/commands.md#list) anymore, use [`ddev stop`](../usage/commands.md#stop)—which is nondestructive—to unlist the project until the next time you run [`ddev start`](../usage/commands.md#start) or [`ddev config`](../usage/commands.md#config):
   110  
   111  ```bash
   112  ddev stop --unlist <projectname>
   113  ```
   114  
   115  ## Importing Assets for An Existing Project
   116  
   117  An important aspect of local web development is the ability to have a precise local recreation of the project you’re working on, including up-to-date database contents and static assets like uploaded images and files. DDEV provides two commands to help with importing assets to your local environment.
   118  
   119  ### Importing a Database
   120  
   121  The [`ddev import-db`](../usage/commands.md#import-db) command imports the database for a project. Running this command will prompt you to specify the location of your database import. By default `ddev import-db` empties the default `db` database, then loads the provided dump file. Most people use it with command flags, like `ddev import-db --file=.tarballs/db.sql.gz`, but it can also prompt for the location of the dump if you only use `ddev import-db`:
   122  
   123  ```bash
   124  ddev import-db
   125  Provide the path to the database you wish to import.
   126  Import path:
   127  ~/Downloads/db.sql
   128  Importing database...
   129  Successfully imported database for drupal8
   130  ```
   131  
   132  #### Supported Database Import File Types
   133  
   134  Database imports can be any of the following file types:
   135  
   136  - Raw SQL Dump (`.sql`)
   137  - Gzipped SQL Dump (`.sql.gz`)
   138  - Xz’d SQL Dump (`.sql.xz`)
   139  - (Gzipped) Tarball Archive (`.tar`, `.tar.gz`, `.tgz`)
   140  - ZIP Archive (`.zip`)
   141  - stdin
   142  
   143  If a Tarball Archive or ZIP Archive is provided for the import, you’ll be prompted to specify a path within the archive to use for the import asset. The specified path should provide a raw SQL dump (`.sql`). In the following example, the database we want to import is named `data.sql` and resides at the top level of the archive:
   144  
   145  ```bash
   146  ddev import-db
   147  Provide the path to the database you wish to import.
   148  Import path:
   149  ~/Downloads/site-backup.tar.gz
   150  You provided an archive. Do you want to extract from a specific path in your archive? You may leave this blank if you wish to use the full archive contents
   151  Archive extraction path:
   152  data.sql
   153  Importing database...
   154  A settings file already exists for your application, so ddev did not generate one.
   155  Run 'ddev describe' to find the database credentials for this application.
   156  Successfully imported database for drupal8
   157  ```
   158  
   159  #### Non-Interactive Usage
   160  
   161  If you want to use the [`import-db`](../usage/commands.md#import-db) command without answering prompts, you can use the `--file` flag to provide the path to the import asset. If you’re importing an archive and wish to specify the path within the archive to extract, you can use the `--extract-path` flag in conjunction with the `--file` flag. Examples:
   162  
   163  ```bash
   164  ddev import-db --file=/tmp/mydb.sql.gz
   165  gzip -dc /tmp/mydb.sql.gz | ddev import-db
   166  ddev import-db <mydb.sql
   167  ```
   168  
   169  #### Database Import Notes
   170  
   171  - Importing from a dump file via stdin will not show progress because there’s no way the import can know how far along through the import it has progressed.
   172  - Use `ddev import-db --target-db <some_database>` to import to a non-default database (other than the default `db` database). This will create the database if it doesn’t already exist.
   173  - Use `ddev import-db --no-drop` to import without first emptying the database.
   174  - If a database already exists and the import does not specify dropping tables, the contents of the imported dumpfile will be _added_ to the database. Most full database dumps do a table drop and create before loading, but if yours does not, you can drop all tables with `ddev stop --remove-data` before importing.
   175  - If imports are stalling or failing, make sure you have plenty of unused space (see [#3360](https://github.com/ddev/ddev/issues/3360)). DDEV has no problems importing large (2G+) databases, but importing requires lots of space. DDEV will show a warning on startup if unused space is getting low.