# Project Setup

The first time you want to use a project, it has to be set up.

For this part of the guide, we will be using a demo project to guide
you through the setup process.

This demo project contains everything you
may encounter while setting up real projects, so we recommend you place this
demo project into an empty directory and follow this guide first before
setting up a real project.

Demo project (place in `riptide.yml` in empty directory):

```yaml
project:
  name: dummy
  src: .
  app:
    name: dummy
    import:
      dummy_directory:
        target: dummy-files
        name: Anything-this-is-just-a-demo
    notices:
      usage: This usage text shows you additional things you need to do when running this project.
    services:
      hello_world:
        image: strm/helloworld-http
        port: 80
        run_as_current_user: false
        roles:
          - main
      db:
        image: mysql:8.0
        roles:
          - db
        driver:
          name: mysql
          config:
            database: dummy
            password: mysql
        run_as_current_user: false
    commands:
      mysql:
        image: "{{ parent().get_service_by_role('db').image }}"
        command: "mysql -hdb -uroot -pmysql dummy"
```

## Running the first-time setup

First, make sure all repositories and Docker images are up to date:

```ansi-console
$ riptide update
── Updating Riptide repositories... ────────────────────────────────────────────────────
Updating 'git@github.com:theCapypara/riptide-repo'...
Done!

── Updating images... ──────────────────────────────────────────────────────────────────
[service/db] Pulling 'mysql:8.0':
    Done!
[service/hello_world] Pulling 'strm/helloworld-http':
    Done!
[command/mysql] Pulling 'mysql:8.0':
    Done!
Done!
```

You should run this command regularly to make sure your images and repositories are always up to date.
See the [Docker documentation](https://docs.docker.com/get-started/#images-and-containers) for more details on images.
See {doc}`repos` for more information on repositories.

To run the first-time setup run:

```ansi-console
$ riptide setup
╭─ 🌊 Welcome! ────────────────────────────────────────────────────────────────────────╮
│ Thank you for using Riptide!                                                         │
│ This command will guide you through the initial setup for 'dummy'.                   │
│ Please follow the instructions carefully, it won't take long!                        │
╰──────────────────────────────────────────────────────────────────────────────────────╯
> Do you wish to run this interactive setup? [y/n] (y): 
```

After starting the setup, confirm with `y`.

:::{tip}
If you accidentally press `n` or make a mistake later during the setup, you can always restart it
by passing the `--force` option.
:::

After pressing `y` you will be asked what kind of setup you want to do:

```ansi-console
> Are you working on a new project that needs to be installed, or do you want to import 
existing data? [n/i] (i): 
```

If you press `n` Riptide will exit and show you instructions for the first-time installation of the application
you are using. Follow these instructions.

If you press `i` you will be guided through the import of existing data. What can be imported depends on the project.
For this dummy project, a MySQL database can be imported, Riptide will tell you this after you pressed `i`:

```ansi-console
== # Setting up an existing project ====================================================
── ## Importing a database ─────────────────────────────────────────────────────────────
> Do you want to import a database (format mysql)? [y/n]: 
```

For this demo, open a text editor and put the following contents in a file called `demo.sql`:

```sql
CREATE TABLE Hello (
    World varchar(255)
);
```

Enter `y` to confirm that you want to import an SQL file:

```ansi-console
> Enter the path to the SQL file: 
```

Enter the path to the SQL file that you just created:

```ansi-console
> Enter the path to the SQL file: demo.sql
╭─ Starting services... ───────────────────────────────────────────────────────────────╮
│ db ⠹ ━━━━━━━━━━━━━━━━━╺━━━━━━━━━━━ 3/5 Starting Container...                        |
╰──────────────────────────────────────────────────────────────────────────────────────╯
```

You can see that the database is now starting, your SQL file will be imported shortly:

```ansi-console
╭─ Starting services... ───────────────────────────────────────────────────────────────╮
│ db   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 5/5 Started!                                     │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Importing database environment ─────────────────────────────────────────────────────╮
│ Database environment 'default' imported.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────╯
```

After the database is imported, the project may ask you to import other directories,
such as directories containing media files or configuration specific to the application:

```ansi-console
── ## Importing files ──────────────────────────────────────────────────────────────────
> Do you want to import the file or directory labeled 'Anything-this-is-just-a-demo' to 
<project>/dummy-files? [y/n]: 
```

In our example it doesn't really matter. You may try this out by confirming with `y` and entering
a path to a directory. It will be copied into the dummy-files directory inside the current directory:

```ansi-console
> Do you want to import the file or directory labeled 'Anything-this-is-just-a-demo' to 
<project>/dummy-files? [y/n]: y
> Enter path of files or directory to copy: /tmp/test_dir
╭─ Importing ──────────────────────────────────────────────────────────────────────────╮
│ Copying dummy_directory (dummy-files) from /tmp/test_dir... this may take a while... │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Importing ──────────────────────────────────────────────────────────────────────────╮
│ File successfully imported.                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────╯

Done importing files.
> Press ENTER to continue...
```

After the import, or after you skipped it, Riptide will inform you that it is done:

```ansi-console
╭─ Project usage instructions ─────────────────────────────────────────────────────────╮
│ This usage text shows you additional things you need to do when running this         │
│ project.                                                                             │
╰──────────────────────────────────────────────────────────────────────────────────────╯

╭─ 🌊 Done! Your project is set up! ───────────────────────────────────────────────────╮
│ After confirming you have done all the steps in the above-printed usage              │
│ documentation, you can now start the project with riptide start.                     │
│ If you need to read the usage instructions again later on, you can run riptide       │
│ notes.                                                                               │
│                                                                                      │
│ Make sure to also have a look at the project's README file, if it has one.           │
│ If you want to use commands like mysql, leave and re-enter the project directory.    │
╰──────────────────────────────────────────────────────────────────────────────────────╯
```

Riptide will also show you the usage notes that are defined for the app your project is using. 
This usage note may contain additional steps you need to run after the setup.

If you need to view this again, run `riptide notes` after the setup.

## Next steps

The project is now set-up. If you are setting up a real project, there may need
to be some additional steps you have to do now, that you were told in the usage notes.
If you need to view these notes again run `riptide notes`. This will show you both
the general usage notes, that may contain things you need to do after importing an existing project,
and installation notes, for starting from scratch.

If you want to import databases or files later on, see {doc}`db`
and {doc}`import`.