# Create your instance

Once you've decided that you want to create your own instance and you've gathered the initial graphic elements ([click here](/en/gettingstarted/prerequisites) to find out more), it's time to create your instance.

?> These steps should be carried out by a developer who is comfortable with the command prompt and `git`. You will need `npm` and a Linux environment.

**What we need to create**

Aktivisda is a static website, which means that in particular there is no database. All data is stored in a **tree of folders and files**: aktivisda expects to find each element in a precise location.
It is then recommended that you store this data **in a Gitlab project** (which is required to use _backtivisda_).

To make Aktivisda accessible, you need to set up a **web server**. And to make backtivisda work, you need to create a **server dedicated to image processing** (or use an existing one). The two remaining steps are to set up a Gitlab runner for continuous integration and a Matomo instance to evaluate site traffic.


## 1. File Tree

To create the file tree, we recommend using the [yeoman] generator (https://yeoman.io/) in an empty folder.

1. Create the folder containing the data for your Aktivisda instance and navigate to it (replace `<myinstance>` with the name of your instance)
```terminal
mkdir <myinstance>
cd <myinstance>
```

2. Retrieve the Aktivisda source code with `git` and save it in a `aktivisda-core` folder. This will allow you to access the generator and launch or compile Aktivisda locally on your computer.
```terminal
git clone https://framagit.org/aktivisda/aktivisda.git aktivisda-core
```

3. Install `yeoman` and then the generator
```terminal
npm install -g yo
cd aktivisda-core/generator-aktivisda
npm install
npm link
```

4. Go to the root of our project (the `<myinstance>` folder), then launch the generator and follow the various steps.
```terminal
yo aktivisda
```
**🥳 Congratulations! You now have the basis for an Aktivisda instance!**

5. Test Aktivisda locally. From the `<myinstance>` folder, run :
```terminal
npm install
npm run serve:aktivisda
```
**Note** : This operation creates symbolic links on your computer using a shell script. You need to be in a Linux environment.

As indicated in the terminal, you can view your Aktvisda instance at url [localhost:8080](http://localhost:8080).
This instance is still an empty shell, with no graphical elements ☹️ (see ticket [#190](https://framagit.org/aktivisda/aktivisda/-/issues/190) to add logos and basic images).

To add items, see the [documentation](/en/admin). To start adding items _via_ backtivisda, you need to complete steps 2 (Gitlab project) and 3 (backtivisda server).

## 2. Gitlab project

**Why Gitlab ?**

Saving data in a Gitlab project has the following advantages:
* make it easier for several people to work together, thanks to the strength of `git`;
* all the features of a gitlab project, in particular continuous integration and ticket management;


In addition, the Gitlab API is used to enable Backtivisda to function.

?> Consideration is being given to an alternative storage solution for Gitlab, see ticket [#181](https://framagit.org/aktivisda/aktivisda/-/issues/181).

1. Create a project on any Gitlab instance :
    * Create a project on any Gitlab instance: Project visibility can be private, internal or public;
    * The Gitlab instance must be accessible on the Internet (or at least accessible by the user's web browser when opening backtivisda);
    * It is possible to use [Framagit](https://framagit.org), an instance offered by the [Framasoft](https://framasoft.org) association , where the source code for Aktivisda is also hosted;
    * Do not initialise with a `readme`;
2.  Follow the instructions that appear on the screen and in particular _"Push an existing folder"_, once in our project, run :
```terminal
git init --initial-branch=main
git remote add origin git@framagit.org:aktivisda/<myinstance>.git
```
3. Make sure there are no local modifications that you don't want to commit, I'm thinking in particular of working files. Working files can be saved in the `_private` folder, which is ignored by `git` by default (_cf._ the `.gitignore` file).

4. If there are no local modifications not to commit, commit all:
```terminal
git add .
git commit -m "Initial commit"
git push --set-upstream origin main
```

5. To use backtivisda you need to update the following variables in the `.env.backtivisda` file (the project ID is available in the Gitlab interface);
```
VUE_APP_GITLAB_PROJECT_ID=xxxxx
VUE_APP_GITLAB_URL="https://framagit.org"
VUE_APP_GITLAB_REPO_URL=/xxx/xxx
```

**🥳 Congratulations! You're just one step away from using Backtivisda!**

## 3. Backtivisda server

!> It seems that recent changes to a dependency have left the server down (see ticket [#191](https://framagit.org/aktivisda/aktivisda/-/issues/191)).

To work, backtivisda needs to connect to an image manipulation server: compression, resizing, vectorisation, etc.

> Don't want to set up your own server? Write to [dev@aktivisda.earth](mailto:dev@aktivisda.earth) to use the community server.

### Authentification

There is an authentication mechanism for limiting access to your image processing server. To initialise it :

1. Go to the `server` folder in the aktivisda project;
2. Generate a `secrets` with python3;
```terminal
python3 -c "import secrets; print(secrets.token_hex())"
```
3. Copy and paste the value into the `.env` file
4. Add a `USERS` variable to the `.env` file, containing the list of usernames authorised to use your instance, each separated by a comma.
```txt
USERS="admin,admin2"
```
5. Create an authentication token for each user entered:
```terminal
python3 scripts/create_token.py admin
python3 scripts/create_token.py admin2
```
Copy and paste these values and keep them safe (it will always be possible to regenerate them)

### Execution

All the server code is in the `server` folder in Aktivisda. In particular, there is a `dockerfile`.

* Compile the Docker image:
```terminal
sudo docker build -t aktivisdaserver:latest .
```

* Launch the Docker image:
```terminal
sudo docker run -p 4000:4000 -t aktivisdaserver:latest
```

**Note** : you need to configure Nginx (and probably apache2) to accept image uploads that are _a little heavy_. It is advisable to add :
```
client_max_body_size 10M;
```

If you go to [localhost:400](https://localhost:4000) you should see "hello world". If so, 🥳 bravo!

### Setting up backtivisda

You can now update the VUE_APP_SERVER_URL variable in the `.env.backtivisda` file:
```
VUE_APP_SERVER_URL="https://server.aktivisda.earth"
```
👉 You can then use [backtivisda](/en/admin/backtivisda)! (*Currently the admin interface is only in French*)

## 4. Web server

?> Lost at this stage? Don't hesitate to write to [dev@aktivisda.earth](mailto:dev@aktivisda.earth) to ask for this section to be expanded. And if **on the contrary** you know exactly what to do, don't hesitate to complete these instructions.

You need to set up a web server, for example with Nginx, and create a user with ssh access to load content from aktivisda.

### Nginx

To allow the user to access all the Aktivisda pages, it is necessary to take care to configure Nginx to tell it to return `index.html` if it does not find a corresponding html file. To do this, add `/index.html` to the `try_files` instruction.

```txt
location / {

    # Path to source
    alias /var/www/<your project>/www/;

    # Default indexes and catch-all
    index index.html;
    try_files $uri $uri/ /index.html;

    # Prevent useless logs
    location = /favicon.ico {
        log_not_found off;
        access_log off;
    }
    location = /robots.txt {
        allow all;
        log_not_found off;
        access_log off;
    }

    # Deny access to hidden files and directories
    location ~ ^/(.+/|)\.(?!well-known\/) {
        deny all;
    }
}

```
## 5. Continuous integration

By default, a `.gitlab-ci.yml` file is present in the project. This calls the `common.gitlab-ci.yml` file in Aktivisda.

This way, you don't have to worry about updating the continuous integration.

There are two stages in continuous integration:
1. Compiling aktivisda and backtivisda using the latest version of aktivisda.
2. FTP upload of the site to the server


### Runner gitlab

To carry out the continuous integration stages, you need a fairly powerful gitlab runner.
(**Todo: documentation to be completed**)

### Parameterisation

!> ⚠️ Be careful to define variables as _protected_.

To make FTP uploading work, you need to create four variable CI/CDs in the Gitlab project:
* `FTP_HOST` with the url (or IP address) to the server. For example `aktivisda.earth`.
* `FTP_PORT` with the `ssh` port number (used to connect using `SFTP`). A priori_ `22` unless specifically configured (but recommended)
* `FTP_PASSWORD` and `FTP_USER` the login credentials.

### Working without continuous integration

It is still possible to deploy Aktivisda without setting up continuous integration. To do this, you need to set up a development environment and then run the :

```terminal
npm run build:aktivisda
npm run build:backtivisda
```

Then move the contents of the `dist` folder to the remote server.

_In case of difficulties, refer to the `common.gitlab-ci.yml` file to find out which commands are up to date._

## 6. Matomo

_(Soon)_